README.txt

README
^^^^^^

  o Environments
    - Installing Cygwin
    - Ubuntu Bash under Windows 10
  o Installation
    - Download and Unpack
    - Semi-Optional apps/ Package
    - Installation Directories with Spaces in the Path
    - Downloading from Repositories
    - Related Repositories
    - Notes about Header Files
  o Configuring NuttX
    - Instantiating "Canned" Configurations
    - Refreshing Configurations
    - NuttX Configuration Tool
    - Finding Selections in the Configuration Menus
    - Reveal Hidden Configuration Options
    - Make Sure that You on on the Right Platform
    - 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

ENVIRONMENTS
^^^^^^^^^^^^

  NuttX may be installed and built on a Linux system or on a Windows
  system if Cygwin is installed.  Instructions for installation of
  Cygwin on Windows system are provided in the following paragraph.

  Other Windows options are

    - The MSYS environment.  However, I have little experience that
      configuration and it will not be discussed in this README file.
      See http://www.mingw.org/wiki/MSYS if you are interested in
      using MSYS.  People report to me that they have used MSYS
      successfully.

    - Ubuntu/bash shell under Windows 10.  This is a new option under
      Windows 10.  I am still looking into this option and do not yet
      have much to say about.  As I learn more, I will update the
      section "Ubuntu Bash under Windows 10" below.

    - 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).

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

  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, network
  installation for you.

  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.

     You should certainly be able to omit "Science", "Math", and
     "Publishing".  You can try omitting KDE, Gnome, GTK, and other
     graphics packages if you don't plan to use them.

  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!

Ubuntu Bash under Windows 10
----------------------------

  A better version of a command-line only Ubuntu under Windows 10 (beta)
  has recently been made available from Microsoft.  I am tinkering with
  that but do not yet have much to say about it.

  Installation
  ------------
  Installation instructions abound on the Internet complete with screen
  shots.  I will attempt to duplicate those instructions in full here.
  Here are the simplified installation steps:

    - Open "Settings".
    - Click on "Update & security".
    - Click on "For Developers".
    - Under "Use developer features", select the "Developer mode" option to
      setup the environment to install Bash.
    - A message box should pop up.  Click "Yes" to turn on developer mode.
    - After the necessary components install, you'll need to restart your
      computer.

  Once your computer reboots:

    - Open "Control Panel".
    - Click on "Programs".
    - Click on "Turn Windows features on or off".
    - A list of features will pop up, check the "Windows Subsystem for Linux
      (beta)" option.
    - Click OK.
    - Once the components installed on your computer, click the "Restart
      now" button to complete the task.

  After your computer restarts, you will notice that Bash will not appear in
  the "Recently added" list of apps, this is because Bash isn't actually
  installed yet. Now that you have setup the necessary components, use the
  following steps to complete the installation of Bash:

    - Open "Start", do a search for bash.exe, and press "Enter".
    - On the command prompt, type y and press Enter to download and install
      Bash from the Windows Store.  This will take awhile.
    - Then you'll need to create a default UNIX user account. This account
      doesn't have to be the same as your Windows account. Enter the
      username in the required field and press Enter (you can't use the
      username "admin").
    - Close the "bash.exe" command prompt.

  Now that you completed the installation and setup, you can open the Bash
  tool from the Start menu like you would with any other app.

  Accessing Windows Files
  -----------------------
  Drivers will be mounted under "/mnt" so for example "C:\Program Files"
  appears at "/mnt/c/Program Files".  This is as opposed to Cgwin where
  the same directory would appear at "/cygdrive/c/Program Files".

  With these differences (perhaps a few other Windows quirks) the Ubuntu
  install works just like Ubuntu running natively on your PC.  Currently
  there is not host configuration for Bash running under Windows 10 but
  setting the host to either Linux or Cygwin should work fine.

  Install Linux Software.
  -----------------------
  Use "sudo apt-get install <package name>"

  Integrating with Windows Tools
  ------------------------------
  If you want to integrate with Windows native tools, then you will need
  deal with the same kind of craziness as with integrating Cygwin with
  native toolchains.  If you set the host PC to Cygwin in this case, then
  the NuttX build system should deal with that craziness for you.

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

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