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
    - Making defconfig Files
    - 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 requires a POSIX development environment such as you would find under
  Linux or OSX.  NuttX may also be installed and built on Windows system
  if you also provide such a POSIX development environment.  Options for a
  POSIX development environment under Windows include:

    - An installation of Linux on a virtual machine (VM) in Windows.  I have
      not been happy using a VM myself.  I have had stability problems with
      open source VMs and commercial VMs cost more than I want to spend.
      Sharing files with Linux running in a VM is awkward;  sharing devices
      connected to the Windows box with Linux in a VM is, at the very least,
      confusing;  Using Windows tools (such as Segger J-Link) with files
      built under the Linux VM is not a possibility.

    - The Cygwin environment.  Instructions for installation of Cygwin on a
      Windows system are provided in the following paragraph, "Installing
      Cygwin".  Cygwin is a mature, well-tested, and very convenient
      environment.  It is especially convenient if you  need to
      integrate with Windows tools and files.  Downsides are that the
      installation time is very long and the compile times are slow.

    - Ubuntu/Bash shell under Windows 10.  This is a new option under
      Windows 10.  See the section "Ubuntu Bash under Windows 10" below.
      This is an improvement over Cygwin if your concern is compile time;
      its build performance is comparable to native Linux, certainly better
      than the Cygwin build time.  It also installs in a tiny fraction of
      the time as Cygwin, perhaps 20 minutes for the basic Ubuntu install
      (vs. more than a day for the complete Cygwin install).

      There have been even more recent ports of Linux environment to
      Windows.  I need to update this section to include some mention of
      these alternatives.

    - The MSYS environment.  I have no experience using the MSYS environment
      and that configuration 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.  I suppose that the advantages of the MSYS environment
      is that it is closer to a native Windows environment and uses only a
      minimal of add-on POSIX-land tools.

    - Other POSIX environments.  Check out:

        UnxUtils: https://sourceforge.net/projects/unxutils/,
          https://en.wikipedia.org/wiki/UnxUtils
        MobaXterm: https://mobaxterm.mobatek.net/
        Gow`: https://github.com/bmatzelle/gow/wiki

      Disclaimer:  In priniple, these should work.  However, I have never
      used any of these environments and cannot guarantee that there is
      not some less-than-obvious issues.

  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" under "Building NuttX" below).  GNUWin32 is used to provide
  compatible native windows tools.

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.

     Perhaps a minimum set would be those packages listed below for the
     "Ubuntu Bash under Windows 10" installation?

  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 EVERYTHING, 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.

  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 from Ubuntu
  -----------------------------------
  File systems will be mounted under "/mnt" so for example "C:\Program Files"
  appears at "/mnt/c/Program Files".  This is as opposed to Cygwin where
  the same directory would appear at "/cygdrive/c/Program Files".