Documentation/Makefile: add make_build_system.rst #17162

tinnedkarma · 2025-10-06T11:31:22Z

Summary

It feels like I am always getting side-tracked while working on NuttX.

Makefile based build system is one of those areas. It seems to be lacking documentation. Most of the features I discovered by actually reading and understanding the Makefiles content.

This PR (I'll keep it in draft for the time being) wants to start that progress. (Do we have a way to compile the documentation locally?)
I am not sure how, or where should I store the files (this whole rst documentation is still new for me).
I'll need help for licensing also. I've copy-pasted the license text into the file, but it seems that my file is the only one that does that. I'll keep documenting as I uncover more about it.

The scope of this PR is just to define how to start, and to document the root Makefile and Unix.mk files.
Smaller chunks of text are easier to process, and I'll need reviews to confirm the content correctness.

Also, feel free to point out what you want to see documented for the make build system

Impact

Improve documentation. More to read, hopefully, also usefull.

Testing

N/A. No impact over the codebase.

acassis · 2025-10-06T12:04:58Z

@tinnedkarma yes, there is a Documentation explaining how to compile the Documentation locally.
Basically you just need to have the right packages installed and execute:
$ cd Documentation
$ make html

simbit18 · 2025-10-06T12:09:55Z

Hi @tinnedkarma , look here
https://nuttx.apache.org/docs/latest/contributing/documentation.html

linguini1 · 2025-10-06T13:17:20Z

Thank you! NuttX has been struggling with documentation so it's good to see improvements in that area.

Documentation/guides/make_build_system.rst

tinnedkarma · 2025-10-07T16:18:34Z

@acassis @linguini1
Do not mind the content, most of it will be reworded.
But, the concept is there, I am not looking to explain in too many words the build flow (as I called it) but rather explain key points, such as files, targets or variables that alters the build process.
Some feedback over this approach early on will be helpful

hartmannathan

This documentation is extremely helpful. Thank you for noticing that it was lacking and for helping to improve it!

hartmannathan · 2025-10-12T15:45:07Z

Documentation/guides/make_build_system.rst

+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+.. License for the specific language governing permissions and limitations
+.. under the License.
+


Agreed that we should probably include the license text in the documentation files. Thanks for doing this here!

I completely disagree with this. It makes the documentation files less readable for terminal users. If it is not required by Apache then we should not clutter the documentation with license headers.

license is added to html output with this file: https://github.com/apache/nuttx/blob/master/Documentation/_templates/layout.html

To be honest, I agree with both.
Though I do not know how the licensing work, if it is per file, as in the productive code base, or it can be per project.
But I completely agree, I also cat files rather than opening the web page, rst is fairly readable in the terminal, less boilerplate is always welcome.

Ok, since it's added automatically, then it's redundant to add it here manually. Let's remove the boilerplate and make the docs more readable :-)

hartmannathan · 2025-10-12T15:45:37Z

Documentation/guides/make_build_system.rst

+Due to *requirements, constraints, and the complexity of the build process*, NuttX divides
+this work into multiple files, each handling specific parts of the build process.
+
+Stated in :doc:`/introduction/inviolables`, multiple platforms should be supported:


Suggested change

Stated in :doc:`/introduction/inviolables`, multiple platforms should be supported:

As stated in :doc:`/introduction/inviolables`, multiple platforms should be supported:

hartmannathan · 2025-10-12T15:46:06Z

Documentation/guides/make_build_system.rst

+
+- :ref:`flatlibs_mk`: Kernel and user-space built into a single `blob`.
+- :ref:`protectedlibs_mk`: Kernel and user-space built as two separate `blobs`.
+- :ref:`kernelibs_mk`: Kernel build into single `blob`. User apps must be loaded 


Suggested change

- :ref:`kernelibs_mk`: Kernel build into single `blob`. User apps must be loaded

- :ref:`kernelibs_mk`: Kernel built into single `blob`. User apps must be loaded

hartmannathan · 2025-10-12T15:46:18Z

Documentation/guides/make_build_system.rst

+- :ref:`kernelibs_mk`: Kernel build into single `blob`. User apps must be loaded 
+  into memory for execution.
+
+NuttX targets multiple libs, or `silos`, each handling it's own compilation:


Suggested change

NuttX targets multiple libs, or `silos`, each handling it's own compilation:

NuttX targets multiple libs, or `silos`, each handling its own compilation:

hartmannathan · 2025-10-12T15:46:44Z

Documentation/guides/make_build_system.rst

+
+.. note::
+
+    Gregory Nutt have a nice presetation about 


Suggested change

Gregory Nutt have a nice presetation about

Gregory Nutt has a nice presentation about

hartmannathan · 2025-10-12T15:46:58Z

Documentation/guides/make_build_system.rst

+    pageId=139629399&preview=/139629402/140774623/nuttx-3-archoverview.pdf>`_
+
+    There the `silo` concept is explained. Only the `silos` there are listed below as libs.
+    The build modes influences the needed libs.


Suggested change

The build modes influences the needed libs.

The build mode influences the needed libs.

hartmannathan · 2025-10-12T15:47:26Z

Documentation/guides/make_build_system.rst

+Verbosity
+---------
+
+The ``V`` variable can be passed to make to control the build verbosity.


Suggested change

The ``V`` variable can be passed to make to control the build verbosity.

The ``V`` variable can be passed to `make` to control the build verbosity.

hartmannathan · 2025-10-12T15:47:59Z

Documentation/guides/make_build_system.rst

+Win.mk
+------
+
+Although targeting different platforms, both **Win.mk** and **Unix.mk** aims the same output.


Suggested change

Although targeting different platforms, both **Win.mk** and **Unix.mk** aims the same output.

Although targeting different platforms, both **Win.mk** and **Unix.mk** aim to produce the same output.

hartmannathan · 2025-10-12T15:48:16Z

Documentation/guides/make_build_system.rst

+------
+
+Although targeting different platforms, both **Win.mk** and **Unix.mk** aims the same output.
+The need for independent files is due to the differences in the platforms approaches.


Suggested change

The need for independent files is due to the differences in the platforms approaches.

The need for independent files is due to the differences in the platforms' approaches.

hartmannathan · 2025-10-12T15:49:27Z

Documentation/guides/make_build_system.rst

+^^^^^^^
+
+The main reason for the use of dummies is to handle some specific scenarios, such as external
+code bases, custom chips and boards or overcome tooling limitation. If any of the features below


Suggested change

code bases, custom chips and boards or overcome tooling limitation. If any of the features below

code bases, custom chips and boards or to overcome tooling limitations. If any of the features below

tinnedkarma · 2025-10-12T20:47:45Z

This documentation is extremely helpful. Thank you for noticing that it was lacking and for helping to improve it!

Hello @hartmannathan,

Thanks for the review, I am still throwing words at random.
English not being my native language doesn't help either.

How was the read, I am a bit worried about the structure of the document being all over the place. I try to summarize the important points of the build system, rather than explain how it works step by step.

Does the content make sense? Would you do things differently?

hartmannathan · 2025-10-12T21:50:06Z

This documentation is extremely helpful. Thank you for noticing that it was lacking and for helping to improve it!

Hello @hartmannathan,

Thanks for the review, I am still throwing words at random.

English not being my native language doesn't help either.

How was the read, I am a bit worried about the structure of the document being all over the place. I try to summarize the important points of the build system, rather than explain how it works step by step.

Does the content make sense? Would you do things differently?

Hello @tinnedkarma, I think this document reads just fine. It gathers together in one place a pretty good high-level description of the build system (at least the Make-based part) that we were lacking for a while. The suggestions I gave in the review are just small grammatical nits to improve the English. No worries if English is not your native language! It's still pretty good :-)

github-actions bot added Area: Documentation Improvements or additions to documentation Size: M The size of the change in this PR is medium labels Oct 6, 2025

acassis requested review from jerpelea and linguini1 October 6, 2025 12:05

tinnedkarma force-pushed the makefile-docs branch from 7f7e1db to d14f316 Compare October 6, 2025 13:28

acassis reviewed Oct 6, 2025

View reviewed changes

Documentation/guides/make_build_system.rst Outdated Show resolved Hide resolved

Documentation/guides/make_build_system.rst Outdated Show resolved Hide resolved

tinnedkarma force-pushed the makefile-docs branch from d14f316 to fbcb4fd Compare October 7, 2025 16:11

tinnedkarma force-pushed the makefile-docs branch from 1e5fdf4 to 029abe2 Compare October 10, 2025 11:28

github-actions bot added Area: Tooling Area: Build system Size: L The size of the change in this PR is large labels Oct 10, 2025

tinnedkarma force-pushed the makefile-docs branch from 029abe2 to 258ed5f Compare October 10, 2025 11:32

github-actions bot removed Area: Tooling Area: Build system labels Oct 10, 2025

tinnedkarma force-pushed the makefile-docs branch from 258ed5f to 9a3f5d0 Compare October 10, 2025 15:41

hartmannathan reviewed Oct 12, 2025

View reviewed changes

Documentation/Makefile: add make_build_system.rst

a25958c

tinnedkarma force-pushed the makefile-docs branch from 9a3f5d0 to a25958c Compare October 16, 2025 10:22

Documentation/Makefile: add more text

8046a42

	Stated in :doc:`/introduction/inviolables`, multiple platforms should be supported:
	As stated in :doc:`/introduction/inviolables`, multiple platforms should be supported:

	- :ref:`kernelibs_mk`: Kernel build into single `blob`. User apps must be loaded
	- :ref:`kernelibs_mk`: Kernel built into single `blob`. User apps must be loaded

	NuttX targets multiple libs, or `silos`, each handling it's own compilation:
	NuttX targets multiple libs, or `silos`, each handling its own compilation:

	Gregory Nutt have a nice presetation about
	Gregory Nutt has a nice presentation about

	The build modes influences the needed libs.
	The build mode influences the needed libs.

	The ``V`` variable can be passed to make to control the build verbosity.
	The ``V`` variable can be passed to `make` to control the build verbosity.

	Although targeting different platforms, both Win.mk and Unix.mk aims the same output.
	Although targeting different platforms, both Win.mk and Unix.mk aim to produce the same output.

	The need for independent files is due to the differences in the platforms approaches.
	The need for independent files is due to the differences in the platforms' approaches.

	code bases, custom chips and boards or overcome tooling limitation. If any of the features below
	code bases, custom chips and boards or to overcome tooling limitations. If any of the features below

Documentation/Makefile: add make_build_system.rst #17162

Are you sure you want to change the base?

Documentation/Makefile: add make_build_system.rst #17162

Conversation

tinnedkarma commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact

Testing

Uh oh!

acassis commented Oct 6, 2025

Uh oh!

simbit18 commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linguini1 commented Oct 6, 2025

Uh oh!

Uh oh!

Uh oh!

tinnedkarma commented Oct 7, 2025

Uh oh!

hartmannathan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raiden00pl Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tinnedkarma commented Oct 12, 2025

Uh oh!

hartmannathan commented Oct 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

tinnedkarma commented Oct 6, 2025 •

edited

Loading

simbit18 commented Oct 6, 2025 •

edited

Loading

raiden00pl Oct 13, 2025 •

edited

Loading