README.txt

README
^^^^^^

  o Installation
    - Installing Cygwin
    - Download and Unpack
    - Semi-Optional apps/ Package
    - Installation Directories with Spaces in the Path
    - Downloading from Repositories
    - Notes about Header Files
  o Configuring NuttX
    - Instantiating "Canned" Configurations
    - Refreshing Configurations
    - NuttX Configuration Tool
    - Finding Selections in the Configuration Menus
    - Comparing Two Configurations
    - Incompatibilities with Older Configurations
    - NuttX Configuration Tool under DOS
  o Toolchains
    - Cross-Development Toolchains
    - NuttX Buildroot Toolchain
  o Shells
  o Building NuttX
    - Building
    - Re-building
    - Build Targets and Options
    - Native Windows Build
    - Installing GNUWin32
  o Cygwin Build Problems
    - Strange Path Problems
    - Window Native Toolchain Issues
  o Documentation

INSTALLATION
^^^^^^^^^^^^

Installing Cygwin
-----------------

  NuttX may be installed and built on a Linux system or on a Windows
  system if Cygwin is installed.  Installing Cygwin on your Windows PC
  is simple, but time consuming.  See http://www.cygwin.com/ for
  installation instructions. Basically you just need to download a
  tiny setup.exe program and it does the real, internet installation
  for you.

     NOTE: NuttX can also be installed and built on a native Windows
     system, but with some potential tool-related issues (see the
     discussion "Native Windows Build" below).

  Some Cygwin installation tips:

  1. Install at C:\cygwin

  2. Install EVERYTHING:  "Only the minimal base packages from the
     Cygwin distribution are installed by default. Clicking on categories
     and packages in the setup.exe package installation screen will
     provide you with the ability to control what is installed or updated.
     Clicking on the "Default" field next to the "All" category will
     provide you with the opportunity to install every Cygwin package.
     Be advised that this will download and install hundreds of megabytes
     to your computer."

     If you use the "default" installation, you will be missing many
     of the Cygwin utilities that you will need to build NuttX.  The
     build will fail in numerous places because of missing packages.

     NOTE: You don't really have to install EVERYTHING but I cannot
     answer the question "Then what should I install?"  I don't know
     the answer to that and so will continue to recommend installing
     EVERYTHING.

  After installing Cygwin, you will get lots of links for installed
  tools and shells.  I use the RXVT native shell.  It is fast and reliable
  and does not require you to run the Cygwin X server (which is neither
  fast nor reliable).  Unless otherwise noted, the rest of these
  instructions assume that you are at a bash command line prompt in
  either Linux or in Cygwin shell.

  UPDATE: The last time I installed EVERTHING, the download was
  about 5GiB.  The server I selected was also very slow so it took
  over a day to do the whole install!

Download and Unpack
-------------------

  Download and unpack the NuttX tarball.  If you are reading this, then
  you have probably already done that.  After unpacking, you will end
  up with a directory called nuttx-version (where version is the NuttX
  version number). You might want to rename that directory nuttx to
  match the various instructions in the documentation and some scripts
  in the source tree.

Semi-Optional apps/ Package
---------------------------

  All NuttX libraries and example code used to be in included within
  the NuttX source tree.  As of NuttX-6.0, this application code was
  moved into a separate tarball, the apps tarball.  If you are just
  beginning with NuttX, then you will want to download the versioned
  apps tarball along with the NuttX tarball.  If you already have your
  own product application directory, then you may not need the apps
  tarball.

  It is call "Semi-optional" because if you don't have some apps/
  directory, NuttX will *fail* to build!

  Download then unpack the apps tarball in the same directory where you
  unpacked the NuttX tarball.  After you unpack the apps tarball, you
  will have a new directory called apps-version (where the version
  should exactly match the version of the NuttX tarball).  Again, you
  might want to rename the directory to simply apps/ to match what
  you read in the documentation

  After unpacking the apps tarball, you will have two directories side
  by side like this:

             |
        +----+----+
        |         |
      nuttx/     apps/

  This is important because the NuttX build will expect to find the
  apps directory in that (default) location.  That default location
  can be changed by editing your NuttX configuration file, but that
  is another story).

Installation Directories with Spaces in the Path
------------------------------------------------

  The nuttx build directory should reside in a path that contains no
  spaces in any higher level directory name.  For example, under
  Cygwin, your home directory might be formed from your first and last
  names like: "/home/First Last". That will cause strange errors when
  the make system tries to build.

  [Actually, that problem is probably not to difficult to fix.  Some
   Makefiles probably just need some paths within double quotes]

  I work around spaces in the home directory name, by creating a
  new directory that does not contain any spaces, such as /home/nuttx.
  Then I install NuttX in /home/nuttx and always build from
  /home/nuttx/nuttx-code.

Downloading from Repositories
-----------------------------

  Cloning the Repository

    The current NuttX du jour is available in from a GIT repository.  Cloning
    instructions are available here:

      https://sourceforge.net/p/nuttx/git

  Configuring the Cone

    Set your identity:

      git config --global user.name "My Name"
      git config --global user.email my.name@example.com

    Colorized diffs are much easier to read:

      git config --global color.branch auto
      git config --global color.diff auto
      git config --global color.interactive auto
      git config --global color.status auto

    Checkout other settings

      git config --list

  Cloning NuttX Inside Cygwin

    If you are cloning the NuttX repository, it is recommended to avoid
    automatic end of lines conversions by git. These conversions may break
    some scripts like configure.sh. Before cloning, do the following:

      git config --global core.autocrlf false

Notes about Header Files
------------------------

  Other C-Library Header Files.

    When a GCC toolchain is built, it must be built against a C library.
    The compiler together with the contents of the C library completes the
    C language definition and provides the complete C development
    environment.  NuttX provides its own, built-in C library.  So the
    complete, consistent C language definition for use with NuttX comes from
    the combination of the compiler and the header files provided by the
    NuttX C library.

    When a GCC toolchain is built, it incorporates the C library header
    files into the compiler internal directories and, in this way, the C
    library really becomes a part of the toolchain.  If you use the NuttX
    buildroot toolchain as described below under under "NuttX Buildroot
    Toolchain", your GCC toolchain will build against the NuttX C library
    and will incorporate the NuttX C library header files as part of the
    toolchain.