[GitHub] [incubator-nuttx] v01d opened a new pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d opened a new pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763


   ## Summary
   
   I've added support for tabbed examples and applied it to quickstart guide. I also worked a bit on the content.
   I focused on the Nucleo F130RB on the running/debugging part since I think it will be easier for the novice to use
   that (I left the JTAG case as an "advanced" example). I don't have that exact board here so it would be good if someone
   else with this board or another Nucleo from STM32F family can test it (I have an STM32L4 Nucleo and a Discovery, which
   requires external hardware to access the UART).
   I also added some instructions on how to nicely display a menu choice, GUI action or keyboard press to the "contributing" section.
   
   I will make a second pass at this later to avoid overcomplicating this PR. For some reason there are duplicate sections for configuration and debugging (with more detail) so I will merge those to the corresponding sections of the Getting Started guide.
   I'm actually wondering if it makes sense to have a so short "quickstart" if we already have a not so long "getting started". I would suggest to just use the latter.
   
   ## Impact
   
   Documentation
   
   ## Testing
   
   Built locally
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487320347



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691392585


   @v01d It does not have a console port that is available via USB, there is no UART-USB bridge on board. So this board doesn't look like a good fit.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487418401



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691582596


   @v01d What do you mean by upstream? If you mean that does the nsh config work out of the box, not quite, it needs a small change to build without errors. The instructions to upload code to the board also may need to change – I did not use OpenOCD, but instead was able to use the embedded STLink mass storage device to simply copy the the `nuttx.bin` to the board. 
   
   I could make a PR and you could decide what to do. Or I'm open to other ideas. What do you think?


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer merged pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer merged pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763


   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487320347



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487330838



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer edited a comment on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer edited a comment on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691395076


   @v01d I take that back, I looked at the [board manual provided by STM](https://www.st.com/resource/en/user_manual/dm00244518-stm32-nucleo144-boards-stmicroelectronics.pdf), and it looks like by default the USB-USART bridge is enabled. The NuttX README may be for a different board. I will have to try it to see if it works.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487341023



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691689915


   @btashton On macOS 10.15 Catalina, at least my system (and it seems many others have this problem too) the macOS Gatekeeper program will not let unsigned binaries run without an exception being created. However, the command line `spctl` tool can not be used to create Gatekeeper exceptions for command line programs. See [this unanswered question](https://discussions.apple.com/thread/250751293) for another description of the problem. Here's [more on Gatekeeper.](https://blog.macsales.com/57866-how-to-work-with-and-around-gatekeeper/).
   
   You can turn off Gatekeeper completely, but that is not ideal.
   
   So to run a NuttX build using the ARM Embedded Toolkit, the only way I found that worked was to manually create the exceptions by running the build. Dialog boxes pop up telling you that the program can't be verified. You can then go into System Preferences > Security & Privacy > General and then click Allow to manually create the Gatekeeper exception. This doesn't activate it though– you need to run the build again, another dialog box pops up to ask you if you really want to run the program.
   
   You have to do this cycle for every binary that the NuttX build uses. It's quite annoying, it took me about 5 minutes of clicking dialog boxes before I could get a working build. Once you've done all this and created the exceptions, the build works fine and macOS doesn't raise any dialog boxes.
   
   If you know a way around this, I would love to know it. It sounds weird, and I know it works on the build boxes, but that method doesn't work on my system. Maybe the build boxes are running an earlier version of macOS? Or maybe they have Gatekeeper disabled? 


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691364879


   LGTM, would @btashton and/or @adamfeuer want to take a look?
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691583436


   > @v01d What do you mean by upstream? If you mean that does the nsh config work out of the box, not quite, it needs a small change to build without errors. The instructions to upload code to the board also may need to change – I did not use OpenOCD, but instead was able to use the embedded STLink mass storage device to simply copy the the `nuttx.bin` to the board.
   
   Yes, i was asking if it requires changes in nuttx for it to work. If you can make a PR with that it would be great.
   Ok, let try to test the openocd instructions because the mass storage way is too dependant on st-link and also cannot be used for debugging. Can you try the commands in the guide? I can help if they fail. You will have to change the target .cfg (and maybe the stlink-v2 to stlink-v2-1.cfg).
   
   > I could make a PR and you could decide what to do. Or I'm open to other ideas. What do you think?
   
   We can also merge this PR and your changes in a second round. The documentation will not go live to the website automatically yet anyway.
   
   
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691392051


   @v01d I haven't tried running NuttX on it yet. It's an STM32H743ZIT6, [which should be supported](https://nuttx.apache.org/docs/latest/introduction/detailed_support.html#stmicro-stm32-h7x3).


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

btashton commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691690767


   @adamfeuer ah yeah I think I set the extended attributes with xattr which looks like what Zephyr also recommends.  So if you keep all your non homebrew files in one place you should be able to authorize them in one go.  https://docs.zephyrproject.org/latest/getting_started/installation_mac.html
   
   I had to use macOS for work for the last few years and I don't miss it one bit, but I also understand how many devs still do. 
   
   I appreciate the testing since I don't have access non Linux/macOS hardware outside of the CI


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691691811


   @btashton That Zephyr recommendation is a cool piece of documentation. I'll include something like that in the macOS instructions.
   
   Re: testing, you're welcome. I usually develop on my Linux system because developing on macOS frustrates me. But for some reason I decided to use it yesterday. I guess it's good because it uncovered this.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691387555






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691586876


   > @v01d I'll make a PR for the nucleo-743zi2 config change.
   
   Great.
   
   > Re: Trying the OpenOCD stuff, I can do that, but not right away– it might be a couple of days.
   
   Sure, take your time.
   Would you consider merging this PR then?
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487413741



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691364879


   LGTM, would @btashton and/or @adamfeuer want to take a look?
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer edited a comment on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer edited a comment on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691395076






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691694272


   @btashton BTW should we add the `xattr` line to the build script, in case the build box changes? Or is it already in another script?


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487437183



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487324191



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer edited a comment on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer edited a comment on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691395076






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691395076


   @v01d I take that back, I looked at the board manual provided by STM, and it looks like by default the USB-USART bridge is enabled. The NuttX README may be for a different board. I will have to try it to see if it works.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691390335






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487415378



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691392358


   > @v01d I haven't tried running NuttX on it yet. It's an STM32H743ZIT6, [which should be supported](https://nuttx.apache.org/docs/latest/introduction/detailed_support.html#stmicro-stm32-h7x3).
   
   Mmm but the STM32H port is "younger" right? I was thinking on a STM32F. Maybe someone else has one. @acassis by any chance you have one?


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691578875


   @v01d Ok, I got the Nucleo 144 to boot NuttX and I have the basic nsh config working– can connect via the USB-UART bridge that's included on the board and on by default (USART3). I also got it all working on MacOS so I can update those instructions too. Installing the ARM tools on macos is quite annoying.
   
   Should I make a PR to your branch?
   
   By the way, the new tabs are really great!
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] xiaoxiang781216 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

xiaoxiang781216 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487409615



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691390335






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691387555


   Thanks @v01d – I will check this out and build it tomorrow. Re: the choice of board, I feel strongly that we should only use a board that at least one of us can actually test these instructions out with. 🙂 I don't have a Nucleo130RB. 
   
   I do have a Nucleo144 which is pretty inexpensive and available. Let me know if you want me to test with that. 


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487416876



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer edited a comment on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer edited a comment on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691395076


   @v01d I take that back, I looked at the [board manual provided by STM](https://www.st.com/resource/en/user_manual/dm00244518-stm32-nucleo144-boards-stmicroelectronics.pdf), and it looks like by default the USB-USART bridge is enabled. The NuttX README may be for a different board. I will have to try it to see if it works.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691364879






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691694782


   👍 


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487322348



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487333837



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487418225



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487320347



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487330081



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487322348



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I will play around in a while to see if I can reproduce it. Do you prefer to leave the "make clean" instruction out?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I've found a case, I will open an issue to discuss it. Anyway, I can open a PR again to remove the "make clean" if needed so no need to hold this for that.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ok, I just added this change.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I'm looking at this right now. It shouldn't be a problem since I see that the *.bdat actually depends on .config. Anyway, if you ever come across this issue again please open an issue.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   
   This is the most problematic. I just verified this is a problem. Any change in flags should trigger a rebuild of files whose flags have changed (the simple approach would be to consider every file affected). I'll open an issue for this.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Please resolve this conversation if you feel it look OK now




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487415378



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] xiaoxiang781216 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

xiaoxiang781216 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487416390



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] xiaoxiang781216 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

xiaoxiang781216 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487409615



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691390335


   > Thanks @v01d – I will check this out and build it tomorrow. Re: the choice of board, I feel strongly that we should only use a board that at least one of us can actually test these instructions out with. slightly_smiling_face I don't have a Nucleo130RB.
   
   Haha, agreed. I just picked a Nucleo at random TBH.
   
   > I do have a Nucleo144 which is pretty inexpensive and available. Let me know if you want me to test with that.
   
   Sure, any Nucleo should do. Is it supported in NuttX? Does it expose UART over USB as well? I think these are the attractive points for such a board.
   
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

btashton commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-693565237


   > @v01d I'll make a PR for the nucleo-743zi2 config change.
   > 
   > Re: Trying the OpenOCD stuff, I can do that, but not right away– it might be a couple of days.
   
   @adamfeuer FYI I just realized that I have this board as well I thought the 144 was a different one so happy to test anything on that.  I will never quite understand board part number naming.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487322348



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "manually" means going into menuconfig in this context. 




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487411462



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       But as you mention these are bugs (in fact, now that you point them out, I will try to address them as well). I don't really like to convey that NuttX simply requires the `make clean` under normal circumstances. I think, considering the situation, I would change this to be a "note" saying something like "since there are currently some issues in NuttX build system, please do make clean after reconfigure". That way it is clear this is not intentional. What do you think?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487325402



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Yes, I think we should address this eventually. I found that sometimes an old .o remains and when building it gets linked as well. It is difficult to reproduce so I always put it off when it happens.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

Ouss4 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487320347



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Are we recommending somewhere to change the configuration file manually?
   We've always been against that.  It's easy to mess things up that way.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       Ah, okay.  My head went elsewhere.
   Did you run into a problem where you needed to clean after changing a config with menuconfig?

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       We've been talking about some similar corner cases around cleaning/distcleaning not long ago.
   Yes, they are all hard to reproduce, it would've been great if we could, then we can address them and eliminate the issue.
   But, of course, this is out of the scope of this PR.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I wanted to.  But this isn't the first time I hear about these corner cases.
   I personally rarely "clean" after a "menuconfig".
   I guess we can keep it for now, and get back to it after some testing.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       "The old *.bdat and *.pdat left under apps/builtin/registy/" is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       > The old *.bdat and *.pdat left under apps/builtin/registy/
   
   is this still an issue?  If I remember correctly this issue lived for a very short time due to a change in the part that generates/cleans those files, but then got fixed rather quickly.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       @xiaoxiang781216 I guess it was introduced and fixed by #1072.  I know it's weird :P but if you had it internally for some time you could've faced the issue.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691387555






----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

btashton commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691605397


   > @v01d Ok, I got the Nucleo 144 to boot NuttX and I have the basic nsh config working– can connect via the USB-UART bridge that's included on the board and on by default (USART3). I also got it all working on MacOS so I can update those instructions too. Installing the ARM tools on macos is quite annoying.
   > 
   > Should I make a PR to your branch?
   > 
   > By the way, the new tabs are really great!
   > 
   
   @adamfeuer what is tricky about ARM on MacOS? This is what we do in the CI for MacOS.
    https://github.com/apache/incubator-nuttx-testing/blob/4388b3e8f71b36446ecb1ae62dacedf08a82228b/cibuild.sh#L154


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691585777


   @v01d I'll make a PR for the nucleo-743zi2 config change. 
   
   Re: Trying the OpenOCD stuff, I can do that, but not right away– it might be a couple of days.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] xiaoxiang781216 commented on a change in pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

xiaoxiang781216 commented on a change in pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#discussion_r487409615



##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       If the user modify defconfig, it's better to make a full build with the current build system, otherwise the strange error happen either at build time or run time. Here is a partial list I have saw so far:
   
   1. Use the wrong compile option if user change CONFIG_DEBUG_OPTLEVEL and related option
   2. The old *.bdat and *.pdat left under apps/builtin/registy/
   3. And issue report here: https://github.com/apache/incubator-nuttx/issues/1764
   
   These issues are hard to debug especially for the newie who doesn't know the flaw inside build system. I would suggest to force the full build if config.h or .config has been changed before we fix all known issues.

##########
File path: Documentation/quickstart/compiling.rst
##########
@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+     
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.

Review comment:
       I am not sure whether all issues get resolved. The build system stop working mysteriously(either build time or run time) after the user make the change through menuconfig which is the top most issue reported in our internal forum.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

btashton commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691694618


   The macOS runners do not seem to have Gatekeeper enabled they are on Catalina so I don't think there is anything to change there.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

adamfeuer commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691602156


   @v01d I had a few extra minutes and got the flashing to work with OpenOCD. On a Mac the instructions to install OpenOCD and flash didn't work, I needed to make some changes, I will update them in a new PR soon.
   
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #1763: documentation: quickstart, add tabs sphinx extension and other improvements

[GitBox <gi...@apache.org>]

v01d commented on pull request #1763:
URL: https://github.com/apache/incubator-nuttx/pull/1763#issuecomment-691579695


   > @v01d Ok, I got the Nucleo 144 to boot NuttX and I have the basic nsh config working– can connect via the USB-UART bridge that's included on the board and on by default (USART3). I also got it all working on MacOS so I can update those instructions too. Installing the ARM tools on macos is quite annoying.
   
   Great, so all this is already upstream?
   
   > Should I make a PR to your branch?
   
   Do you think it will be a large change? Wouldn't want this PR to grow too much.
   
   > By the way, the new tabs are really great!
   
   :+1: 
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org