Skip to content
README.txt 56.5 KiB
Newer Older
patacongo's avatar
patacongo committed
README
^^^^^^

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

patacongo's avatar
patacongo committed
INSTALLATION
^^^^^^^^^^^^

Gregory Nutt's avatar
Gregory Nutt committed
  NuttX may be installed and built on a Linux system or on a Windows
  system if Cygwin is installed.  The MSYS environment is an option
  to Cygwin on the Windows platform.  However, I have little experience
  that that configuration and it will not be discussed in this README
  file.

  Instructions for installation of Cygwin on a Windows are provided
  in the following the provided paragraph.

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

patacongo's avatar
patacongo committed
Installing Cygwin
patacongo's avatar
patacongo committed

Gregory Nutt's avatar
Gregory Nutt committed
  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.
patacongo's avatar
patacongo committed
  Some Cygwin installation tips:
patacongo's avatar
patacongo committed
  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."
patacongo's avatar
patacongo committed
     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.

Gregory Nutt's avatar
Gregory Nutt committed
     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.

patacongo's avatar
patacongo committed
  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
patacongo's avatar
patacongo committed
  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.
patacongo's avatar
patacongo committed

Gregory Nutt's avatar
Gregory Nutt committed
  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
---------------------------
patacongo's avatar
patacongo committed

  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/
Gregory Nutt's avatar
Gregory Nutt committed
  directory, NuttX will *fail* to build! You you do not necessarily
  need to use use the NuttX apps tarball and may, instead, provide
  your own custom application directory.
patacongo's avatar
patacongo committed

Gregory Nutt's avatar
Gregory Nutt committed
  Download then unpack the apps tarball in the same directory where you
patacongo's avatar
patacongo committed
  unpacked the NuttX tarball.  After you unpack the apps tarball, you
  will have a new directory called apps-version (where the version
patacongo's avatar
patacongo committed
  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
patacongo's avatar
patacongo committed
  After unpacking the apps tarball, you will have two directories side
  by side like this:
patacongo's avatar
patacongo committed
             |
        +----+----+
        |         |
      nuttx/     apps/

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

Installation Directories with Spaces in the Path
------------------------------------------------
patacongo's avatar
patacongo committed

  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
patacongo's avatar
patacongo committed
   Makefiles probably just need some paths within double quotes]
patacongo's avatar
patacongo committed

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

Gregory Nutt's avatar
Gregory Nutt committed

Gregory Nutt's avatar
Gregory Nutt committed
    The current NuttX du jour is available in from a GIT repository.  Here are
    instructions for cloning the core NuttX RTOS (corresponding to the nuttx
    tarball discussed above)::

      git clone https://bitbucket.org/patacongo/nuttx.git nuttx

    And the semi-optional apps/ application directory and be clone like:

      git clone https://bitbucket.org/nuttx/apps.git apps

    That will give you a directory structure like this:

             |
        +----+----+
        |         |
      nuttx/     apps/
  Initialize Sub-Modules

    The NuttX repository contains GIT sub-modules for the Documentation/,
    arch/, and configs/ directories. These may need to be individually
    initialized:

      cd nuttx
      git submodule init
      git submodule update

  Configuring the Clone
Gregory Nutt's avatar
Gregory Nutt committed

Gregory Nutt's avatar
Gregory Nutt committed
    The following steps need to be performed for each of the two
    repositories.  After changing to the clone directory:

Gregory Nutt's avatar
Gregory Nutt committed
    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:

Loading full blame...