1# APACHE NUTTX 2 3* Introduction 4* Community 5 - Getting Help 6 - Mailing Lists 7 - Issue Tracker 8 - Source Code 9 - Website Source Code 10* Environments 11 - Installing Cygwin 12 - Ubuntu Bash under Windows 10 13 - Using macOS 14* Installation 15 - Download and Unpack 16 - Semi-Optional apps/ Package 17 - Installation Directories with Spaces in the Path 18 - Downloading from Repositories 19 - Related Repositories 20 - Notes about Header Files 21* Configuring NuttX 22 - Instantiating "Canned" Configurations 23 - Refreshing Configurations 24 - NuttX Configuration Tool 25 - Finding Selections in the Configuration Menus 26 - Reveal Hidden Configuration Options 27 - Make Sure that You are on the Right Platform 28 - Comparing Two Configurations 29 - Making defconfig Files 30 - Incompatibilities with Older Configurations 31 - NuttX Configuration Tool under DOS 32* Toolchains 33 - Cross-Development Toolchains 34 - NuttX Buildroot Toolchain 35* Shells 36* Building NuttX 37 - Building 38 - Re-building 39 - Build Targets and Options 40 - Native Windows Build 41 - Installing GNUWin32 42* Cygwin Build Problems 43 - Strange Path Problems 44 - Window Native Toolchain Issues 45* Documentation 46 47# INTRODUCTION 48 49Apache NuttX is a real-time operating system (RTOS) with an emphasis on 50standards compliance and small footprint. Scalable from 8-bit to 64-bit 51microcontroller environments, the primary governing standards in NuttX are 52POSIX and ANSI standards. Additional standard APIs from Unix and other 53common RTOSs (such as VxWorks) are adopted for functionality not available 54under these standards, or for functionality that is not appropriate for 55deeply-embedded environments (such as fork()). 56 57Extensive documentation can be found on the project wiki: 58 <https://cwiki.apache.org/NUTTX/NuttX> 59 60For brevity, many parts of the documentation will refer to Apache NuttX as 61simply NuttX. 62 63# COMMUNITY 64 65Every volunteer project obtains its strength from the people involved in 66it. We invite you to participate as much or as little as you choose. 67 68We encourage you to: 69 70 - Use our project and provide feedback. 71 - Provide us with use-cases. 72 - Report bugs and submit patches. 73 - Contribute code or documentation. 74 75## Getting Help 76 77The best place to get help is the developer's mailing list. Please see 78the following section: 79 80## Mailing Lists 81 82Get help using NuttX or contribute to the project on our mailing lists: 83 84 * <dev@nuttx.apache.org> is for people who want to contribute code to NuttX. 85 * To subscribe, send an email to <dev-subscribe@nuttx.apache.org>. 86 * To unsubscribe, send an email to <dev-unsubscribe@nuttx.apache.org>. 87 * View the archives at: 88 <https://www.mail-archive.com/dev@nuttx.apache.org/> 89 90 * <commits@nuttx.apache.org> is a read-only list that notifies subscribers 91 about commit messages and patches to NuttX. 92 * To subscribe, send an email to <commits-subscribe@nuttx.apache.org>. 93 * To unsubscribe, send an email to <commits-unsubscribe@nuttx.apache.org>. 94 * View the archives at: 95 <https://www.mail-archive.com/commits@nuttx.apache.org/> 96 97## Reporting Security Issues 98 99Found a vulnerability? See our security policy [here](.github/SECURITY.md). 100 101## Issue Tracker 102 103### Bug Reports: 104 105Found bug? Send an email to the dev list: <dev@nuttx.apache.org> 106 107Before submitting an issue, please: 108 109 - Verify that the bug does in fact exist. 110 111 - Search the mailing list archives to verify there is no existing issue 112 reporting the bug you've found. 113 114 - Consider tracking down the bug yourself in the NuttX source code and 115 submitting a patch along with your bug report. This is a great time 116 saver for the NuttX developers and helps ensure the bug will be fixed 117 quickly. 118 119### Feature Requests: 120 121Enhancement requests for new features are also welcome. The more concrete 122and rational the request is, the greater the chance it will incorporated 123into future releases. 124 125## Source Code 126 127The project sources are in two Git repositories. The core OS is in nuttx 128and the apps repository is in nuttx-apps. These are housed in GitBox on 129ASF servers and also mirrored at GitHub. These are kept in sync, so you 130can use whichever option you prefer. 131 132 - NuttX core OS repository: 133 134 - Primary: 135 <https://gitbox.apache.org/repos/asf?p=nuttx.git> 136 137 - GitHub Mirror: 138 <https://github.com/apache/nuttx> 139 140 - Apps repository: 141 142 - Primary: 143 <https://gitbox.apache.org/repos/asf?p=nuttx-apps.git> 144 145 - GitHub Mirror: 146 <https://github.com/apache/nuttx-apps> 147 148## Website Source Code 149 150The project website sources are accessible via the website source code 151 repository which is also mirrored in GitHub: 152 153- Primary: 154 <https://gitbox.apache.org/repos/asf?p=nuttx-website.git> 155 156- GitHub Mirror: 157 <https://github.com/apache/nuttx-website> 158 159# ENVIRONMENTS 160 161 NuttX requires a POSIX development environment such as you would find under 162 Linux or macOS. NuttX may also be installed and built on Windows system 163 if you also provide such a POSIX development environment. Options for a 164 POSIX development environment under Windows include: 165 166 - An installation of Linux on a virtual machine (VM) in Windows. I have 167 not been happy using a VM myself. I have had stability problems with 168 open source VMs and commercial VMs cost more than I want to spend. 169 Sharing files with Linux running in a VM is awkward; sharing devices 170 connected to the Windows box with Linux in a VM is, at the very least, 171 confusing; Using Windows tools (such as Segger J-Link) with files 172 built under the Linux VM is not a possibility. 173 174 - The Cygwin environment. Instructions for installation of Cygwin on a 175 Windows system are provided in the following paragraph, "Installing 176 Cygwin". Cygwin is a mature, well-tested, and very convenient 177 environment. It is especially convenient if you need to 178 integrate with Windows tools and files. Downsides are that the 179 installation time is very long and the compile times are slow. 180 181 - Ubuntu/Bash shell under Windows 10. This is a new option under 182 Windows 10. See the section "Ubuntu Bash under Windows 10" below. 183 This is an improvement over Cygwin if your concern is compile time; 184 its build performance is comparable to native Linux, certainly better 185 than the Cygwin build time. It also installs in a tiny fraction of 186 the time as Cygwin, perhaps 20 minutes for the basic Ubuntu install 187 (vs. more than a day for the complete Cygwin install). 188 189 There have been even more recent ports of Linux environment to 190 Windows. I need to update this section to include some mention of 191 these alternatives. 192 193 - The MSYS environment. MSYS derives from an older version of Cygwin 194 simplified and adapted to work more naturally in the Windows 195 environment. See <http://www.mingw.org/wiki/MSYS> if you are 196 interested in using MSYS. The advantages of the MSYS environment is 197 that it is better integrted with the native Windows environment and 198 lighter weight; it uses only a minimal number of add-on POSIX-land 199 tools. 200 201 The download link in that Wiki takes you to the SourceForge download 202 site. The SourceForge MSYS project has been stagnant for some time. 203 The MSYS project has more recently moved to 204 <http://odsn.net/projects/sfnet_mingwbundle>. Downloads of current .zip 205 files are available there but no instructions for the installation. 206 207 - MSYS2 appears to be a re-write of MSYS based on a newer version of 208 Cygwin. Is it available at <https://www.msys2.org>. A windows 209 installer is available at that site along with very good installation 210 instructions. The download is relatively quick (at least compared to 211 Cygwin) and the 'pacman' package management tool supports supports 212 simple system updates. For example, 'pacman -S git' will install the 213 GIT command line utilities. 214 215 - Other POSIX environments. Check out: 216 217 - UnxUtils: <https://sourceforge.net/projects/unxutils/>, 218 <https://en.wikipedia.org/wiki/UnxUtils> 219 - MobaXterm: <https://mobaxterm.mobatek.net/> 220 - Gow: <https://github.com/bmatzelle/gow/wiki> 221 222 **Disclaimer**: In principle, these should work. However, I have never 223 used any of these environments and cannot guarantee that there is 224 not some less-than-obvious issues. 225 226NuttX can also be installed and built on a native Windows system, but with 227some potential tool-related issues (see the discussion "Native Windows 228Build" under "Building NuttX" below). GNUWin32 is used to provide 229compatible native windows tools. 230 231## Installing Cygwin 232 233Installing Cygwin on your Windows PC is simple, but time consuming. See 234<http://www.cygwin.com/> for installation instructions. Basically you just 235need to download a tiny setup.exe program and it does the real, network 236installation for you. 237 238Some Cygwin installation tips: 239 240 1. Install at `C:\cygwin` 241 242 2. Install **everything**: "Only the minimal base packages from the 243 Cygwin distribution are installed by default. Clicking on categories 244 and packages in the setup.exe package installation screen will 245 provide you with the ability to control what is installed or updated. 246 Clicking on the "Default" field next to the "All" category will 247 provide you with the opportunity to install every Cygwin package. 248 Be advised that this will download and install hundreds of megabytes 249 to your computer." 250 251If you use the "default" installation, you will be missing many 252of the Cygwin utilities that you will need to build NuttX. The 253build will fail in numerous places because of missing packages. 254 255NOTE: The last time I installed **everything**, the download was 256about 5GiB. The server I selected was also very slow so it took 257over a day to do the whole install! 258 259NOTE: You don't really have to install **everything** but I cannot 260answer the question "Then what should I install?" I don't know 261the answer to that and so will continue to recommend installing 262**everything**. 263 264You should certainly be able to omit "Science", "Math", and 265"Publishing". You can try omitting KDE, Gnome, GTK, and other 266graphics packages if you don't plan to use them. 267 268Perhaps a minimum set would be those packages listed below for the 269"Ubuntu Bash under Windows 10" installation? 270 271**UPDATE**: Sergey Frolov had success with the following minimal 272Cygwin configuration: 273 274 1. After starting the Cygwin installer, keep the recommended 275 packages that are pre-selected in the default configuration. 276 277 2. Using the installation tools, add the following packages: 278 279 make (GNU make) bison libgmp3-dev 280 gcc-core byacc libmpfr-dev 281 gcc-g++ gperf libmpc-dev 282 flex gdb automake-1.15 283 libncurses-dev libgmp-dev curl 284 285After installing Cygwin, you will get lots of links for installed 286tools and shells. I use the RXVT native shell. It is fast and reliable 287and does not require you to run the Cygwin X server (which is neither 288fast nor reliable). Unless otherwise noted, the rest of these 289instructions assume that you are at a bash command line prompt in 290either Linux or in Cygwin shell. 291 292## Using MSYS 293 294MSYS is an environment the derives from Cygwin. Thus, most things said 295about Cygwin apply equally to MSYS. This section will, then, focus on 296the differences when using MSYS, specifically MSYS2. 297 298Here is it assumed that you have already downloaded and installed MSYS2 299from https://www.msys2.org using the windows installer available at that 300location. It is also assumed that you have brought in the necessary 301tools using the 'pacman' package management tool Tools needed including: 302 303 pacman -S git 304 pacman -S make 305 pacman -S gcc 306 pacman -S gdb 307 308And possibly others depending upon your usage. Then you will need to 309build and install kconfig-frontends per the instructions of the top-level 310README.txt file in the tools repository. This requires the following 311additional tools: 312 313 pacman -S bison 314 pacman -S curl 315 pacman -S gperf 316 pacman -S ncurses-devel 317 pacman -S automake-wrapper 318 pacman -S autoconf 319 pacman -S pkg-config 320 321Because of some versioning issues, I had to run 'aclocal' prior to 322running the kconfig-frontends configure script. See "Configuring NuttX" 323below for further information. 324 325Unlike Cygwin, MSYS does not support symbolic links. The 'ln -s' command 326will, in fact, copy a directory! This means that you Make.defs file will 327have to include definitions like: 328 329 ifeq ($(CONFIG_WINDOWS_MSYS),y) 330 DIRLINK = $(TOPDIR)/tools/copydir.sh 331 DIRUNLINK = $(TOPDIR)/tools/unlink.sh 332 endif 333 334This will force the directory copies to work in a way that can be handled 335by the NuttX build system. NOTE: The default link.sh script has been 336updated so that is should now be MSYS2 compatible. The above is preferred 337but no longer necessary in the Make.defs file. 338 339To build the simulator under MSYS, you also need: 340 341 pacman -S zlib-devel 342 343It appears that you cannot use directory names with spaces in them like 344"/c/Program\ Files \(86\)" in the MSYS path variable. I worked around this 345by create Windows junctions like this: 346 347 1. Open the a windows command terminal, 348 349 2. cd to `c:\msys64`, then 350 351 3. `mklink /j programfiles "C:/Program\ Files"` and 352 353 4. `mklink /j programfiles86 "C:/Program\ Files\ \(x86\)"` 354 355 They then show up as `/programfiles` and `/programfiles86` with the MSYS2 356 sandbox. Those paths can then be used with the PATH variable. I had 357 to do something similar for the path to the GNU Tools "ARM Embedded 358 Toolchain" which also has spaces in the path name. 359 360## Ubuntu Bash under Windows 10 361 362A better version of a command-line only Ubuntu under Windows 10 (beta) 363has recently been made available from Microsoft. 364 365### Installation 366 367Installation instructions abound on the Internet complete with screen 368shots. I will attempt to duplicate those instructions in full here. 369Here are the simplified installation steps: 370 371 - Open *Settings*. 372 373 - Click on *Update & security*. 374 375 - Click on *For Developers*. 376 377 - Under *Use developer features*, select the *Developer mode* option to 378 setup the environment to install Bash. 379 380 - A message box should pop up. Click *Yes* to turn on developer mode. 381 382 - After the necessary components install, you'll need to restart your 383 computer. 384 385 Once your computer reboots: 386 387 - Open *Control Panel*. 388 389 - Click on *Programs*. 390 391 - Click on *Turn Windows features on or off*. 392 393 - A list of features will pop up, check the *Windows Subsystem for Linux 394 (beta)* option. 395 396 - Click *OK*. 397 398 - Once the components installed on your computer, click the *Restart 399 now* button to complete the task. 400 401 After your computer restarts, you will notice that Bash will not appear in 402 the *Recently added* list of apps, this is because Bash isn't actually 403 installed yet. Now that you have setup the necessary components, use the 404 following steps to complete the installation of Bash: 405 406 - Open *Start*, do a search for `bash.exe`, and press *Enter*. 407 408 - On the command prompt, type `y` and press Enter to download and install 409 Bash from the Windows Store. This will take awhile. 410 411 - Then you'll need to create a default UNIX user account. This account 412 doesn't have to be the same as your Windows account. Enter the 413 username in the required field and press Enter (you can't use the 414 username `admin`). 415 416 - Close the `bash.exe` command prompt. 417 418 Now that you completed the installation and setup, you can open the Bash 419 tool from the Start menu like you would with any other app. 420 421### Accessing Windows Files from Ubuntu 422 423File systems will be mounted under `/mnt` so for example `C:\Program Files` 424appears at `/mnt/c/Program Files`. This is as opposed to Cygwin where 425the same directory would appear at `/cygdrive/c/Program Files`. 426 427With these differences (perhaps a few other Windows quirks) the Ubuntu 428install works just like Ubuntu running natively on your PC. 429 430A good tip for file sharing is to use symbolic links within your Ubuntu 431home directory. For example, suppose you have your `projects` directory 432at `C:\Documents\projects`. Then you can set up a link to the `projects/` 433directory in your Ubuntu directory like: 434 435 ln -s /mnt/c/Documents/projects projects 436 437### Accessing Ubuntu Files From Windows 438 439In Ubuntu Userspace for Windows, the Ubuntu file system root directory is 440at: 441 442 %localappdata%\lxss\rootfs 443 444Or 445 446 C:\Users\Username\AppData\Local\lxss\rootfs 447 448However, I am unable to see my files under the rootfs\home directory. 449After some looking around, I find the home directory 450`%localappdata%\lxss\home`. 451 452With that trick access to the `/home` directory, you should actually be 453able to use Windows tools outside of the Ubuntu sandbox with versions of 454NuttX built within the sandbox using that path. 455 456### Executing Windows Tools from Ubuntu 457 458You can also execute Windows tools from within the Ubuntu sandbox: 459 460 /mnt/c/Program\ Files\ \(x86\)/Microchip/xc32/v1.43/bin/xc32-gcc.exe --version 461 Unable to translate current working directory. Using C:\WINDOWS\System32 462 xc32-gcc.exe (Microchip Technology) 4.8.3 MPLAB XC32 Compiler v1.43 Build date: Mar 1 2017 463 ... 464 465The error message indicates that there are more issues: You cannot mix 466Windows tools that use Windows style paths in an environment that uses 467POSIX paths. I think you would have to use Linux tools only from within 468the Ubuntu sandbox. 469 470### Install Ubuntu Software 471 472Use `sudo apt-get install <package name>`. As examples, this is how 473you would get GIT: 474 475 sudo apt-get install git 476 477This will get you a compiler for your host PC: 478 479 sudo apt-get install gcc 480 481This will get you an ARM compiler for your target: 482 483 sudo apt-get install gcc-arm-none-eabi 484 485**NOTE**: That is just an example. I am not sure if apt-get will give you a 486current or usable compiler. You should carefully select your toolchain 487for the needs of your project. 488 489You will also need to get the kconfig-frontends configuration as 490described below under *NuttX Configuration Tool*. In order to build the 491kconfig-frontends configuration tool you will also need: `make`, `gperf`, 492`flex`, `bison`, and `libncurses-dev`. 493 494That is enough to do a basic NuttX build. 495 496### Integrating with Windows Tools 497 498If you want to integrate with Windows native tools, then you would need 499deal with the same kind of craziness as with integrating Cygwin with 500native toolchains, see the section *Cygwin Build Problems* below. 501 502However, there is currently no build support for using Windows native 503tools with Ubuntu under Windows. This tool combination is made to work 504with Cygwin through the use of the `cygpath -w` tool that converts paths 505from say `/cydrive/c/Program Files` to `C:\Program Files`. There is, 506however, no corresponding tool to convert `/mnt/c/Program Files` in the 507Ubuntu environment. 508 509### Graphics Support 510 511The Ubuntu version support by Microsoft is a command-line only version. 512There is no support for Linux graphics utilities. 513 514This limitation is not a limitation of Ubuntu, however, only in what 515Microsoft is willing to support. If you install a X-Server, then you 516can also use basic graphics utilities. See for example: 517 518 <http://www.howtogeek.com/261575/how-to-run-graphical-linux-desktop-applications-from-windows-10s-bash-shell/> 519 520Many Linux graphics programs would, however, also require a graphics 521framework like GTK or Qt. So this might be a trip down the rabbit hole. 522 523### Using macOS 524 525You need to install at least the following tools specific to macOS 526if you want to build the sim: 527 528 * Xcode (the native compiler and the rest of the toolchain) 529 530 * ELF toolchain (if you want to build modules for CONFIG_LIBC_MODLIB) 531 532 brew install x86_64-elf-gcc 533 534# INSTALLATION 535 536There are two ways to get NuttX: You may download released, stable 537tarballs from either the project website. Or you may get NuttX by 538cloning the GIT repositories. Let's consider the released tarballs 539first: 540 541## Download and Unpack 542 543Download and unpack the NuttX tarball. If you are reading this, then 544you have probably already done that. After unpacking, you will end 545up with a directory called nuttx-version (where version is the NuttX 546version number). You might want to rename that directory nuttx to 547match the various instructions in the documentation and some scripts 548in the source tree. 549 550 * Download location: 551 552 <https://nuttx.apache.org/download/> 553 554 * Legacy download locations: 555 556 <https://bitbucket.org/nuttx/nuttx/downloads> 557 <https://sourceforge.net/projects/nuttx/files/nuttx/> 558 559## Semi-Optional apps/ Package 560 561All NuttX libraries and example code used to be in included within 562the NuttX source tree. As of NuttX-6.0, this application code was 563moved into a separate tarball, the apps tarball. If you are just 564beginning with NuttX, then you will want to download the versioned 565apps tarball along with the NuttX tarball. If you already have your 566own product application directory, then you may not need the apps 567tarball. 568 569It is called "Semi-optional" because if you don't have some `apps/` 570directory, NuttX will *fail* to build! You do not necessarily need 571to use the NuttX apps tarball but may, instead, provide your own 572custom application directory. Such a custom directory would need 573to include a valid Makefile to support the build and a valid Kconfig 574file to support the configuration. More about these files later. 575 576Download then unpack the apps tarball in the same directory where you 577unpacked the NuttX tarball. After you unpack the apps tarball, you 578will have a new directory called apps-version (where the version 579should exactly match the version of the NuttX tarball). Again, you 580might want to rename the directory to simply apps/ to match what 581you read in the documentation 582 583After unpacking (and renaming) the apps tarball, you will have two 584directories side by side like this: 585 586 | 587 +----+----+ 588 | | 589 nuttx/ apps/ 590 591This is important because the NuttX build will expect to find the 592apps directory in that (default) location. That default location 593can be changed by modifying your NuttX configuration file, but that 594is another story. 595 596## Installation Directories with Spaces in the Path 597 598The nuttx build directory should reside in a path that contains no 599spaces in any higher level directory name. For example, under 600Cygwin, your home directory might be formed from your first and last 601names like: `/home/First Last`. That will cause strange errors when 602the make system tries to build. 603 604[Actually, that problem is probably not too difficult to fix. Some 605 Makefiles probably just need some paths within double quotes] 606 607I work around spaces in the home directory name, by creating a 608new directory that does not contain any spaces, such as `/home/nuttx`. 609Then I install NuttX in `/home/nuttx` and always build from 610`/home/nuttx/nuttx-code`. 611 612## Downloading from Repositories 613 614### Cloning the Repository 615 616**BEFORE** cloning repositories on any Windows platform do the following GIT 617command: 618 619 git config --global core.autocrlf false 620 621That will avoid conversions of linefeeds (newlines, \n) to carriage 622return plus linefeed sequences (\r\n) 623 624The current NuttX du jour is available in from a GIT repository. Here are 625instructions for cloning the core NuttX RTOS (corresponding to the nuttx 626tarball discussed above): 627 628 git clone https://gitbox.apache.org/repos/asf/nuttx.git nuttx 629 630-or- 631 632 git clone https://github.com/apache/nuttx.git nuttx 633 634And the semi-optional apps/ application directory and be cloned like: 635 636 git clone https://gitbox.apache.org/repos/asf/nuttx-apps.git apps 637 638-or- 639 640 git clone https://github.com/apache/nuttx-apps.git apps 641 642That will give you the same directory structure like this: 643 644 | 645 +----+----+ 646 | | 647 nuttx/ apps/ 648 649### Configuring the Clones 650 651The following steps need to be performed for each of the repositories. 652After changing to the clone directory: 653 654Set your identity: 655 656 git config --global user.name "My Name" 657 git config --global user.email my.name@example.com 658 659Colorized diffs are much easier to read: 660 661 git config --global color.branch auto 662 git config --global color.diff auto 663 git config --global color.interactive auto 664 git config --global color.status auto 665 666Checkout other settings 667 668 git config --list 669 670### Cloning NuttX Inside Cygwin 671 672If you are cloning the NuttX repository, it is recommended to avoid 673automatic end of lines conversions by git. These conversions may break 674some scripts like configure.sh. Before cloning, do the following: 675 676 git config --global core.autocrlf false 677 678## Related Repositories 679 680These are standalone repositories: 681 682 * <https://gitbox.apache.org/repos/asf/nuttx-apps> 683 or 684 <https://github.com/apache/nuttx-apps.git> 685 686 This directory holds an optional package of applications and libraries 687 can be used with the NuttX RTOS. There is a README.txt file there that 688 will provide more information about that package. 689 690 * <https://bitbucket.org/nuttx/nxwidgets> 691 692 This is the NuttX C++ graphics support. This includes NxWM, the tiny 693 NuttX Window Manager. 694 695 * <https://bitbucket.org/nuttx/uclibc> 696 697 This repository contains a version of the uClibc++ C++ library. This code 698 originates from <http://cxx.uclibc.org/> and has been adapted for NuttX by the 699 RGMP team (<http://rgmp.sourceforge.net/wiki/index.php/Main_Page>). 700 701 * <https://bitbucket.org/nuttx/buildroot> 702 703 A environment that you can to use to build a custom, NuttX GNU toolchain. 704 705 * <https://bitbucket.org/nuttx/tools> 706 707 There are snapshots of some tools here that you will need to work with 708 NuttX: kconfig-frontends, genromfs, and others. 709 710## Notes about Header Files 711 712### Other C-Library Header Files 713 714When a GCC toolchain is built, it must be built against a C library. 715The compiler together with the contents of the C library completes the 716C language definition and provides the complete C development 717environment. NuttX provides its own, built-in C library. So the 718complete, consistent C language definition for use with NuttX comes from 719the combination of the compiler and the header files provided by the 720NuttX C library. 721 722When a GCC toolchain is built, it incorporates the C library header 723files into the compiler internal directories and, in this way, the C 724library really becomes a part of the toolchain. If you use the NuttX 725buildroot toolchain as described below under "NuttX Buildroot 726Toolchain", your GCC toolchain will build against the NuttX C library 727and will incorporate the NuttX C library header files as part of the 728toolchain. 729 730If you use some other, third-party tool chain, this will not be the 731case, however. Those toolchains were probably built against some 732other, incompatible C library distribution (such as newlib). Those 733tools will have incorporated the incompatible C library header files 734as part of the toolchain. These incompatible header files must *not* 735be used with NuttX because they will conflict with definitions in the 736NuttX built-in C-Library. For such toolchains that include header 737files from a foreign C-Library, NuttX must be compiled without using 738the standard header files that are distributed with your toolchain. 739This prevents including conflicting, incompatible header files such 740as stdio.h. 741 742The math.h and stdarg.h are probably the two most trouble some header 743files to deal with. These troublesome header files are discussed in 744more detail below. 745 746### Header Files Provided by Your Toolchain 747 748Certain header files, such as `setjmp.h`, `stdarg.h`, and `math.h`, may still 749be needed from your toolchain and your compiler may not, however, be able 750to find these if you compile NuttX without using standard header files 751(i.e., with `-nostdinc`). If that is the case, one solution is to copy 752those header file from your toolchain into the NuttX include directory. 753 754### Duplicated Header Files 755 756There are also a few header files that can be found in the `nuttx/include` 757directory which are duplicated by the header files from your toolchain. 758stdint.h and stdbool.h are examples. If you prefer to use the `stdint.h` 759and `stdbool.h` header files from your toolchain, those could be copied 760into the `nuttx/include/` directory. Using most other header files from 761your toolchain would probably cause errors. 762 763### math.h 764 765Even though you should not use a foreign C-Library, you may still need 766to use other, external libraries with NuttX. In particular, you may 767need to use the math library, libm.a. NuttX supports a generic, built-in 768math library that can be enabled using `CONFIG_LIBM=y`. However, you may 769still want to use a higher performance external math library that has 770been tuned for your CPU. Sometimes such tuned math libraries are 771bundled with your toolchain. 772 773The math library header file, `math.h`, is a then special case. If you do 774nothing, the standard math.h header file that is provided with your 775toolchain will be used. 776 777If you have a custom, architecture specific math.h header file, then 778that header file should be placed at `arch/<cpu>/include/math.h`. There 779is a stub `math.h` header file located at `include/nuttx/lib/math.h`. This stub 780header file can be used to "redirect" the inclusion to an architecture- 781specific math.h header file. If you add an architecture specific math.h 782header file then you should also define `CONFIG_ARCH_MATH_H=y` in your 783NuttX Configuration file. If `CONFIG_ARCH_MATH_H` is selected, then the 784top-level Makefile will copy the stub math.h header file from 785`include/nuttx/lib/math.h` to `include/math.h` where it will become the system 786`math.h` header file. The stub `math.h` header file does nothing other 787than to include that architecture-specific `math.h` header file as the 788system `math.h` header file. 789 790### float.h 791 792If you enable the generic, built-in math library, then that math library 793will expect your toolchain to provide the standard `float.h` header file. 794The float.h header file defines the properties of your floating point 795implementation. It would always be best to use your toolchain's `float.h` 796header file but if none is available, a default `float.h` header file will 797be provided if this option is selected. However, there is no assurance 798that the settings in this `float.h` are actually correct for your platform! 799 800### stdarg.h 801 802In most cases, the correct version of stdarg.h is the version provided 803with your toolchain. However, sometimes there are issues with 804using your toolchains `stdarg.h`. For example, it may attempt to draw in 805header files that do not exist in NuttX or perhaps the header files that 806it uses are not compatible with the NuttX header files. In those cases, 807you can use an architecture-specific `stdarg.h` header file by defining 808`CONFIG_ARCH_STDARG_H=y`. 809 810See the discussion above for the `math.h` header. This setting works 811exactly the same for the `stdarg.h` header file. 812 813# CONFIGURING NUTTX 814 815## Instantiating "Canned" Configurations 816 817### `configure.sh` and `configure.bat` 818 819"Canned" NuttX configuration files are retained in: 820 821 boards/<arch-name>/<chip-name>/<board-name>/configs/<config-dir> 822 823Where `<board-name>` is the name of your development board and `<config-dir>` 824is the name of the sub-directory containing a specific configuration for 825that board. `<arch-name>` and `<chip-name>` refer to characteristics of the 826MCU used on the board: `<arch-name>` is the CPU architecture implemented 827by the MCU; `<chip-name>` identifies the MCU chip family. Only a few 828steps are required to instantiate a NuttX configuration, but to make the 829configuration even easier there are scripts available in the tools/ 830sub-directory combines those simple steps into one command. 831 832There is one tool for use with any Bash-like shell that does configuration 833steps. It is used as follows: 834 835 tools/configure.sh <board-name>:<config-dir> 836 837There is an alternative Windows batch file that can be used in the windows 838native environment like: 839 840 tools\configure.bat <board-name>:<config-dir> 841 842And, to make sure that other platforms are supported, there is also a 843C program at tools/configure.c that can be compiled to establish the 844board configuration. 845 846See `tools/README.txt` for more information about these scripts. 847 848General information about configuring NuttX can be found in: 849 850 {TOPDIR}/boards/README.txt 851 {TOPDIR}/boards/<arch-name>/<chip-name>/<board-name>/README.txt 852 853### The Hidden Configuration Scripts: 854 855As mentioned above, there are only a few simple steps to instantiating a 856NuttX configuration. Those steps are hidden by the configuration scripts 857but are summarized below: 858 859 1. Copy Files 860 861 Configuring NuttX requires only copying two files from the 862 `<config-dir>` to the directory where you installed NuttX (TOPDIR): 863 864 * Copy `boards/<arch-name>/<chip-name>/<board-name>/configs/<config-dir>/Make.def` to `{TOPDIR}/Make.defs` 865 866 OR 867 868 * Copy `boards/<arch-name>/<chip-name>/<board-name>/scripts/Make.def` 869 to `{TOPDIR}/Make.defs` 870 871 Make.defs describes the rules needed by your tool chain to compile 872 and link code. You may need to modify this file to match the 873 specific needs of your toolchain. NOTE that a configuration may 874 have its own unique Make.defs file in its configuration directory or 875 it may use a common Make.defs file for the board in the scripts/ 876 directory. The first takes precedence. 877 878 * Copy `boards/<arch-name>/<chip-name>/<board-name>/configs/<config-dir>/defconfig` to `{TOPDIR}/.config` 879 880 The defconfig file holds the actual build configuration. This 881 file is included by all other make files to determine what is 882 included in the build and what is not. This file is also used 883 to generate a C configuration header at `include/nuttx/config.h`. 884 885 * Copy other, environment-specific files to `{TOPDIR}` 886 887 This might include files like .gdbinit or IDE configuration files 888 like .project or .cproject. 889 890 2. Refresh the Configuration 891 892 New configuration setting may be added or removed. Existing settings 893 may also change there values or options. This must be handled by 894 refreshing the configuration as described below. 895 896 NOTE: NuttX uses only compressed defconfig files. For the NuttX 897 defconfig files, this refreshing step is *NOT* optional; it is also 898 necessary to uncompress and regenerate the full making file. This is 899 discussed further below. 900 901## Refreshing Configurations 902 903Configurations can get out of date. As new configuration settings are 904added or removed or as dependencies between configuration settings 905change, the contents of a default configuration can become out of synch 906with the build systems. Hence, it is a good practice to "refresh" each 907configuration after configuring and before making. To refresh the 908configuration, use the NuttX Configuration Tool like this: 909 910 make oldconfig 911 912AFTER you have instantiated the NuttX configuration as described above. 913The configuration step copied the .config file into place in the top-level 914NuttX directory; 'make oldconfig' step will then operate on that .config 915file to bring it up-to-date. 916 917If your configuration is out of date, you will be prompted by 'make oldconfig' 918to resolve the issues detected by the configuration tool, that is, to 919provide values for the new configuration options in the build system. Doing 920this can save you a lot of problems down the road due to obsolete settings in 921the default board configuration file. The NuttX configuration tool is 922discussed in more detail in the following paragraph. 923 924Confused about what the correct value for a new configuration item should 925be? Enter ? in response to the 'make oldconfig' prompt and it will show 926you the help text that goes with the option. 927 928If you don't want to make any decisions are willing to just accept the 929recommended default value for each new configuration item, an even easier 930way is: 931 932 make olddefconfig 933 934The olddefconfig target will simply bring your configuration up to date with 935the current Kconfig files, setting any new options to the default value. 936No questions asked. 937 938## NuttX Configuration Tool 939 940An automated tool has been incorporated to support re-configuration 941of NuttX. This tool is based on the kconfig-frontends application available 942at <https://bitbucket.org/nuttx/tools/src/master/kconfig-frontends/>. (This 943is a snapshot of the old <http://ymorin.is-a-geek.org/projects/kconfig-frontends> 944which is no longer available.) This application provides a tool called 945`kconfig-mconf` that is used by the NuttX top-level Makefile. The following 946make target is provided: 947 948 make menuconfig 949 950This make target will bring up NuttX configuration menus. 951 952**WARNING**: Never do `make menuconfig` on a configuration that has 953not been converted to use the kconfig-frontends tools! This will 954damage your configuration (see 955<https://cwiki.apache.org/confluence/display/NUTTX/Converting+Legacy+Configurations+to+Use+kconfig-mconf>). 956 957NuttX also supports kconfiglib(https://github.com/ulfalizer/Kconfiglib) by default, 958which is a Kconfig tool implemented in Python 2/3. Compared with kconfig-frontends, 959kconfiglib provides NuttX with the possibility of multi-platform support(configure 960NuttX in Winodws native/Visual Studio), and also kconfiglib has a stronger Kconfig 961syntax check, this will help developers to avoid some Kconfig syntax errors. 962Install kconfiglib via following command: 963 964 pip install kconfiglib 965 966If you are a working on Windows, which also need the support of windows-curses: 967 968 pip install windows-curses 969 970**NOTE**: It should be noted that kconfiglib does not support **modules** attributes. 971(<https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py#L3239-L3254>, 972the community seems to have stopped updating), if the features depends on 973`CONFIG_BUILD_LOADABLE`, kconfiglib may not be a good choice. 974 975How do we tell a new configuration from an old one? See "Incompatibilities 976with Older Configurations" below. 977 978The `menuconfig` make target depends on two things: 979 980 1. The Kconfig configuration data files that appear in almost all 981 NuttX directories. These data files are the part that is still 982 under development (patches are welcome!). The Kconfig files 983 contain configuration information for the configuration settings 984 relevant to the directory in which the Kconfig file resides. 985 986 NOTE: For a description of the syntax of this configuration file, 987 see kconfig-language.txt in the tools repository at 988 <https://bitbucket.org/nuttx/tools> 989 990 2. The `kconfig-mconf` tool. `kconfig-mconf` is part of the 991 kconfig-frontends package. You can download that package from the 992 snapshot in the tools repository at <https://bitbucket.org/nuttx/tools>. 993 994 Building kconfig-frontends under Linux may be as simple as 995 `configure; make; make install` but there may be some build 996 complexities, especially if you are building under Cygwin. See 997 the more detailed build instructions in the top-level README.txt 998 file of the tools repository at <https://bitbucket.org/nuttx/tools>. 999 1000 The `make install` step will, by default, install the `kconfig-mconf` 1001 tool at `/usr/local/bin/mconf`. Where ever you choose to 1002 install `kconfig-mconf`, make certain that your PATH variable includes 1003 a path to that installation directory. 1004 1005 The kconfig-frontends tools will not build in a native Windows 1006 environment directly "out-of-the-box". For the Windows native 1007 case, you can use the modified version of kconfig-frontends 1008 that can be found at 1009 1010 <http://uvc.de/posts/linux-kernel-configuration-tool-kconfig-under-windows.html> 1011 1012 or a more recent port that can be found at 1013 1014 <http://reclonelabs.com/more-kconfig-awesomeness-for-windows/>. 1015 1016The basic configuration order is "bottom-up": 1017 1018 - Select the build environment, 1019 - Select the processor, 1020 - Select the board, 1021 - Select the supported peripherals 1022 - Configure the device drivers, 1023 - Configure the application options on top of this. 1024 1025This is pretty straight forward for creating new configurations 1026but may be less intuitive for modifying existing configurations. 1027 1028Another ncurses-based tool that is an option to kconfig-mconf is 1029kconfig-nconf. The differences are primary in in the aesthetics of the 1030UI. If you have kconfig-nconf built, then you can invoke that front end 1031with: 1032 1033 make nconfig 1034 1035If you have an environment that supports the Qt or GTK graphical systems 1036(probably KDE or gnome, respectively, or Cygwin under Windows with Qt or 1037GTK installed), then you can also build the graphical kconfig-frontends, 1038kconfig-qconf and kconfig-gconf. In these case, you can start the 1039graphical configurator with either: 1040 1041 make qconfig 1042 1043 or 1044 1045 make gconfig 1046 1047Some keyboard shortcuts supported by kconfig-mconf, the tool that runs 1048when you do 'make menuconfig': 1049 1050 - `?` will bring up the mconfig help display. 1051 1052 - `/` can be used find configuration selections. 1053 1054 - `Z` can be used to reveal hidden configuration options 1055 1056These last two shortcuts are described further in the following 1057paragraphs. 1058 1059## Finding Selections in the Configuration Menus 1060 1061The NuttX configuration options have gotten complex and it can be very 1062difficult to find options in the menu trees if you are not sure where 1063to look. The "basic configuration order" describe above can help to 1064narrow things down. 1065 1066But if you know exactly what configuration setting you want to select, 1067say `CONFIG_XYZ`, but not where to find it, then the `make menuconfig` 1068version of the tool offers some help: By pressing the '/' key, the 1069tool will bring up a menu that will allow you to search for a 1070configuration item. Just enter the string `CONFIG_XYZ` and press ENTER. 1071It will show you not only where to find the configuration item, but 1072also all of the dependencies related to the configuration item. 1073 1074## Reveal Hidden Configuration Options 1075 1076If you type `Z`, then `kconfig-mconf` will change what is displayed. 1077Normally, only enabled features that have all of their dependencies met 1078are displayed. That is, of course, not very useful if you would like to 1079discover new options or if you are looking for an option and do not 1080realize that the dependencies have not yet been selected and, hence, it 1081is not displayed. 1082 1083But if you enter `Z`, then every option will be shown, whether or not its 1084dependencies have been met. You can then see everything that could be 1085selected with the right dependency selections. These additional options 1086will be shown the `-` for the selection and for the value (since it 1087cannot be selected and has no value). About all you do is to select 1088the `<Help>` option to see what the dependencies are. 1089 1090## Make Sure that You are on the Right Platform 1091 1092Saved configurations may run on Linux, Cygwin (32- or 64-bit), or other 1093platforms. The platform characteristics can be changed use `make 1094menuconfig`. Sometimes this can be confusing due to the differences 1095between the platforms. Enter `sethost.sh` 1096 1097sethost.sh is a simple script that changes a configuration to your 1098host platform. This can greatly simplify life if you use many different 1099configurations. For example, if you are running on Linux and you 1100configure like this: 1101 1102 tools/configure.sh board:configuration 1103 1104The you can use the following command to both (1) make sure that the 1105configuration is up to date, AND (2) the configuration is set up 1106correctly for Linux: 1107 1108 tools/sethost.sh -l 1109 1110Or, if you are on a Windows/Cygwin 64-bit platform: 1111 1112 tools/sethost.sh -c 1113 1114Or, for MSYS/MSYS2: 1115 1116 tools/sethost.sh -g 1117 1118Other options are available from the help option built into the 1119script. You can see all options with: 1120 1121 tools/sethost.sh -h 1122 1123Recently, the options to the configure.sh (and configure.bat) scripts have 1124been extended so that you both setup the configuration, select for the host 1125platform that you use, and uncompress and refresh the defconfig file all in 1126one command like: 1127 1128 tools/configure.sh -l board:configuration 1129 1130For a Linux host or for a Windows/Cygwin host: 1131 1132 tools/configure.sh -c board:configuration 1133 1134Other options are available from the help option built into the 1135script. You can see all options with: 1136 1137 tools/configure.sh -h 1138 1139## Comparing Two Configurations 1140 1141If you try to compare two configurations using 'diff', you will probably 1142not be happy with the result. There are superfluous things added to 1143the configuration files that make comparisons with the human eye 1144difficult. 1145 1146There is a tool at nuttx/tools/cmpconfig.c that can be built to simplify 1147these comparisons. The output from this difference tool will show only 1148the meaningful differences between two configuration files. This tool is 1149built as follows: 1150 1151 cd nuttx/tools 1152 make -f Makefile.host 1153 1154This will create a program called 'cmpconfig' or 'comconfig.exe' on Windows. 1155 1156Why would you want to compare two configuration files? Here are a few 1157of the reasons why I do this 1158 1159 1. When I create a new configuration I usually base it on an older 1160 configuration and I want to know, "What are the options that I need to 1161 change to add the new feature to the older configurations?" For example, 1162 suppose that I have a boardA/nsh configuration and I want to create a 1163 boardA/nxwm configuration. Suppose I already have boardB/nsh and 1164 boardB/nxwm configurations. Then by comparing the boardB/nsh with the 1165 boardB/nxwm I can see the modifications that I would need to make to my 1166 boardA/nsh to create a new boardA/nxwm. 1167 1168 2. But the most common reason that I use the 'cmpconfig' program is to 1169 check the results of "refreshing" a configuration with 'make oldconfig' 1170 (see the paragraph "Refreshing Configurations" above). The 'make 1171 oldconfig' command will make changes to my configuration and using 1172 'cmpconfig', I can see precisely what those changes were and if any 1173 should be of concern to me. 1174 1175 3. The 'cmpconfig' tool can also be useful when converting older, legacy 1176 manual configurations to the current configurations based on the 1177 kconfig-frontends tools. See the following paragraph. 1178 1179## Making `defconfig` Files 1180 1181### `.config` Files as `defconfig` Files: 1182 1183The minimum `defconfig` file is simply the generated `.config` file with 1184CONFIG_APPS_DIR setting removed or commented out. That setting provides 1185the name and location of the `apps/` directory relative to the `nuttx` build 1186directory. The default is `../apps/`, however, the apps directory may be 1187any other location and may have a different name. For example, the name 1188of versioned NuttX releases are always in the form `apps-xx.yy` where `xx.yy` 1189is the version number. 1190 1191### Finding the `apps/` Directory Path: 1192 1193When the default configuration is installed using one of the scripts or 1194programs in the NuttX tools directory, there will be an option to provide 1195the path to the `apps/` directory. If not provided, then the configure tool 1196will look around and try to make a reasonable decision about where the 1197`apps/` directory is located. 1198 1199### Compressed `defconfig` Files: 1200 1201The `Makefile` also supports an option to generate very small `defconfig` 1202files. The `.config` files are quite large and complex. But most of the 1203settings in the `.config` file simply have the default settings from the 1204`Kconfig` files. These `.config` files can be converted into small `defconfig` 1205file: 1206 1207 make savedefconfig 1208 1209That make target will generate a defconfig file in the top-level 1210directory. The size reduction is really quite remarkable: 1211 1212 wc -l .config defconfig 1213 1085 .config 1214 82 defconfig 1215 1167 total 1216 1217In order to be usable, the `.config` file installed from the compressed 1218defconfig file must be reconstituted using: 1219 1220 make olddefconfig 1221 1222 > **NOTE 1**: Only compressed defconfig files are retained in the NuttX repository. 1223 > All patches and PRs that attempt to add or modify a defconfig file MUST 1224 > use the compressed defconfig format as created by 'make savdefconfig.' 1225 1226 > **NOTE 2**: When 'make savedefconfig' runs it will try several things some of 1227 > which are expected to fail. In these cases you will see an error message 1228 > from make followed by "(ignored)." You should also ignore these messages 1229 1230**CAUTION**: This size reduction was accomplished by removing all setting 1231from the `.config` file that were at the default value. `make olddefconfig` 1232can regenerate the original `.config` file by simply restoring those default 1233settings. The underlying assumption here is, of course, that the default 1234settings do not change. If the default settings change, and they often 1235do, then the original `.config` may not be reproducible. 1236 1237So if your project requires 100% reproducibility over a long period of 1238time, you make want to save the complete `.config` files vs. the standard, 1239compressed `defconfig` file. 1240 1241### Configuring with "Compressed" defconfig Files: 1242 1243As described above `defconfig`, all NuttX `defconfig` files are compressed 1244using `make savedeconfig`. These compressed `defconfig` files are 1245generally not fully usable as they are and may not build the target 1246binaries that you want because the compression process removed all of 1247the default settings from the `defconfig` file. To restore the default 1248settings, you should run the following after configuring: 1249 1250 make olddefconfig 1251 1252That will restore the the missing defaulted values. 1253 1254Using this command after configuring is generally a good practice anyway: 1255Even if the `defconfig` files are not "compressed" in this fashion, the 1256`defconfig` file may be old and the only way to assure that the installed 1257`.config` is is up to date is via `make oldconfig` or `make olddefconfig`. 1258See the paragraph above entitled "Refreshing Configurations" for 1259additional information. 1260 1261## Incompatibilities with Older Configurations 1262 1263**WARNING** 1264 1265The current NuttX build system supports *only* the new compressed, 1266`defconfig` configuration files generated using the `kconfig-frontends` tools 1267as described in the preceding section. Support for the older, legacy, 1268manual configurations was eliminated in NuttX 7.0; support for 1269uncompressed `.config-files-as-defconfig` files was eliminated after 1270NuttX-7.21. All configurations must now be done using the 1271`kconfig-frontends` tool. The older manual configurations and the new 1272`kconfig-frontends` configurations are not compatible. Old legacy 1273configurations can *not* be used with the `kconfig-frontends` tool and, 1274hence, cannot be used with releases of NuttX 7.0 and beyond: 1275 1276If you run `make menuconfig` with a legacy configuration the resulting 1277configuration will probably not be functional. 1278 1279 > Q: How can I tell if a configuration is a new kconfig-frontends 1280 > configuration or an older, manual configuration? 1281 > 1282 > A: Only old, manual configurations will have an appconfig file 1283 > 1284 > Q: How can I convert a older, manual configuration into a new, 1285 > kconfig-frontends toolchain. 1286 > 1287 > A: Refer to <https://cwiki.apache.org/confluence/display/NUTTX/Converting+Legacy+Configurations+to+Use+kconfig-mconf> 1288 1289**WARNING** 1290 1291As described above, whenever you use a configuration, you really should 1292always refresh the configuration with the following command *before* you 1293make NuttX: 1294 1295 make oldconfig 1296 1297OR 1298 1299 make olddefconfig 1300 1301This will make sure that the configuration is up-to-date in the event that 1302it has lapsed behind the current NuttX development (see the paragraph 1303"Refreshing Configurations" above). But this only works with *new* 1304configuration files created with the kconfig-frontends tools. 1305 1306Further, this step is *NOT* optional with the new, compressed defconfig 1307files. It is a necessary step that will also uncompress the defconfig 1308file, regenerating the `.config` and making it usable for NuttX builds. 1309 1310Never do `make oldconfig` (OR `make menuconfig`) on a configuration that 1311has not been converted to use the kconfig-frontends tools! This will 1312damage your configuration (see 1313<https://cwiki.apache.org/confluence/display/NUTTX/Converting+Legacy+Configurations+to+Use+kconfig-mconf>). 1314 1315## NuttX Configuration Tool under DOS 1316 1317 Recent versions of NuttX support building NuttX from a native Windows 1318 console window (see *Native Windows Build* below). But `kconfig-frontends` 1319 is a Linux tool. At one time this was a problem for Windows users, but 1320 now there are two specially modified versions of the `kconfig-frontends` 1321 tools that can be used. One can be found here: 1322 <http://uvc.de/posts/linux-kernel-configuration-tool-kconfig-under-windows.html> 1323 1324 The configuration steps of the most recent versions of NuttX require the 1325 `kconfig-tweak` tool that is not not available in the the above. However, 1326 there has been an update to this `Kconfig` Windows tools that does include 1327 `kconfig-tweak`: http://reclonelabs.com/more-kconfig-awesomeness-for-windows/ 1328 1329 Source code is available here: <https://github.com/reclone/kconfig-frontends-win32> 1330 and <https://github.com/reclone/kconfig-frontends-win32/releases> 1331 1332 It is also possible to use the version of `kconfig-frontends` built 1333 under Cygwin outside of the Cygwin *sandbox* in a native Windows 1334 environment: 1335 1336 1. You can run the configuration tool using Cygwin. However, the 1337 Cygwin `Win.mk` will complain so to do this will, you have 1338 to manually edit the `.config` file: 1339 1340 a. Delete the line: `CONFIG_WINDOWS_NATIVE=y` 1341 1342 b. Change the apps/ directory path, `CONFIG_APPS_DIR` to use Unix 1343 style delimiters. For example, change `..\apps` to `../apps` 1344 1345 And of course, after you use the configuration tool you need to 1346 restore `CONFIG_WINDOWS_NATIVE=y` and the correct `CONFIG_APPS_DIR`. 1347 1348 2. You can, with some effort, run the Cygwin `kconfig-mconf` tool 1349 directly in the Windows console window. In this case, you do not 1350 have to modify the `.config` file, but there are other complexities: 1351 1352 a. You need to temporarily set the Cygwin directories in the PATH 1353 variable then run `kconfig-mconf` manually like: 1354 1355 kconfig-mconf Kconfig 1356 1357 There is a Windows batch file at `tools/kconfig.bat` that automates 1358 these steps: 1359 1360 tools/kconfig menuconfig 1361 1362 b. There is an issue with accessing DOS environment variables from 1363 the Cygwin `kconfig-mconf` running in the Windows console. The 1364 following change to the top-level `Kconfig` file seems to work 1365 around these problems: 1366 1367 config APPSDIR 1368 string 1369 - option env="APPSDIR" 1370 + default "../apps" 1371 1372# TOOLCHAINS 1373 1374## Cross-Development Toolchains 1375 1376 In order to build NuttX for your board, you will have to obtain a cross- 1377 compiler to generate code for your target CPU. For each board, 1378 configuration, there is a `README.txt` file (at 1379 `boards/<arch-name>/<chip-name>/<board-name>/README.txt`). 1380 That README file contains suggestions and information about appropriate 1381 tools and development environments for use with your board. 1382 1383 In any case, the PATH environment variable will need to be updated to 1384 include the location where the build can find the toolchain binaries. 1385 1386## NuttX Buildroot Toolchain 1387 1388 For many configurations, a DIY set of tools is available for NuttX. These 1389 tools can be downloaded from the NuttX Bitbucket.org file repository. After 1390 unpacking the buildroot tarball, you can find instructions for building 1391 the tools in the `buildroot/boards/README.txt` file. 1392 1393 Check the README.txt file in the configuration directory for your board 1394 to see if you can use the buildroot toolchain with your board (this 1395 README.txt file is located in 1396 `boards/<arch-name>/<chip-name>/<board-name>/README.txt`). 1397 1398 This toolchain is available for both the Linux and Cygwin development 1399 environments. 1400 1401 Advantages: (1) NuttX header files are built into the tool chain, 1402 and (2) related support tools like NXFLAT tools, the ROMFS 1403 genromfs tools, and the kconfig-frontends tools can be built into your 1404 toolchain. 1405 1406 Disadvantages: This tool chain is not was well supported as some other 1407 toolchains. GNU tools are not my priority and so the buildroot tools 1408 often get behind. For example, until recently there was no EABI support 1409 in the NuttX buildroot toolchain for ARM. 1410 1411 NOTE: For Cortex-M3/4, there are OABI and EABI versions of the buildroot 1412 toolchains. If you are using the older OABI toolchain the prefix for 1413 the tools will be `arm-nuttx-elf-`; for the EABI toolchain the prefix will 1414 be `arm-nuttx-eabi-`. If you are using the older OABI toolchain with 1415 an ARM Cortex-M3/4, you will need to set CONFIG_ARM_TOOLCHAIN_BUILDROOT_OABI 1416 in the `.config` file in order to pick the right tool prefix. 1417 1418 If the make system ever picks the wrong prefix for your toolchain, you 1419 can always specify the prefix on the command to override the default 1420 like: 1421 1422 make CROSSDEV=arm-nuttx-elf 1423 1424# SHELLS 1425 1426The NuttX build relies on some shell scripts. Some are inline in the 1427Makefiles and many are executable scripts in the `tools/`. directory. The 1428scripts were all developed using bash and many contain bash shell 1429dependencies. 1430 1431Most of the scripts begin with `#!/bin/bash` to specifically select the 1432bash shell. Some still have `#!/bin/sh` but I haven't heard any complaints 1433so these must not have bash dependencies. 1434 1435There are two shell issues that I have heard of: 1436 1437 1. Linux where `/bin/sh` refers to an incompatible shell (like `ksh` or `csh`). 1438 1439 In this case, bash is probably available and the `#!/bin/bash` at the 1440 beginning of the file should do the job. If any scripts with `#!/bin/sh` 1441 fail, try changing that to `#!/bin/bash` and let me know about the change. 1442 1443 2. FreeBSD with the Bourne Shell and no bash shell. 1444 1445 The other, reverse case has also been reported on FreeBSD setups that 1446 have the Bourne shell, but not bash. In this base, `#!/bin/bash` fails 1447 but `#!/bin/sh` works okay. My recommendation in this case is to create 1448 a symbolic link at `/bin/bash` that refers to the Bourne shell. 1449 1450 There may still be issues, however, with certain the `bash`-centric scripts 1451 that will require modifications. 1452 1453# BUILDING NUTTX 1454 1455## Building 1456 1457NuttX builds in-place in the source tree. You do not need to create 1458any special build directories. Assuming that your Make.defs is setup 1459properly for your tool chain and that PATH environment variable contains 1460the path to where your cross-development tools are installed, the 1461following steps are all that are required to build NuttX: 1462 1463 cd {TOPDIR} 1464 make 1465 1466At least one configuration (eagle100) requires additional command line 1467arguments on the make command. Read 1468`{TOPDIR}/boards/<arch-name>/<chip-name>/<board-name>/README.txt` to see 1469if that applies to your target. 1470 1471## Re-building 1472 1473Re-building is normally simple -- just type make again. 1474 1475But there are some things that can "get you" when you use the Cygwin 1476development environment with Windows native tools. The native Windows 1477tools do not understand Cygwin's symbolic links, so the NuttX make system 1478does something weird: It copies the configuration directories instead of 1479linking to them (it could, perhaps, use the NTFS `mklink` command, but it 1480doesn't). 1481 1482A consequence of this is that you can easily get confused when you edit 1483a file in one of the linked (i.e., copied) directories, re-build NuttX, 1484and then not see your changes when you run the program. That is because 1485build is still using the version of the file in the copied directory, not 1486your modified file! 1487 1488Older versions of NuttX did not support dependencies in this 1489configuration. So a simple work around this annoying behavior in this 1490case was the following when you re-build: 1491 1492 make clean_context all 1493 1494This 'make' command will remove of the copied directories, re-copy them, 1495then make NuttX. 1496 1497However, more recent versions of NuttX do support dependencies for the 1498Cygwin build. As a result, the above command will cause everything to be 1499rebuilt (because it removes and will cause recreating the 1500`include/nuttx/config.h` header file). A much less gracefully but still 1501effective command in this case is the following for the ARM configuration: 1502 1503 rm -rf arch/arm/src/chip arch/arm/src/board 1504 1505This "kludge" simple removes the copied directories. These directories 1506will be re-created when you do a normal 'make' and your edits will then be 1507effective. 1508 1509## Build Targets and Options 1510 1511### Build Targets 1512 1513Below is a summary of the build targets available in the top-level 1514NuttX Makefile: 1515 1516 * `all` 1517 1518 The default target builds the NuttX executable in the selected output 1519 formats. 1520 1521 * `clean` 1522 1523 Removes derived object files, archives, executables, and temporary 1524 files, but retains the configuration and context files and directories. 1525 1526 * `distclean` 1527 1528 Does 'clean' then also removes all configuration and context files. 1529 This essentially restores the directory structure to its original, 1530 unconfigured stated. 1531 1532Application housekeeping targets. The APPDIR variable refers to the user 1533application directory. A sample `apps/` directory is included with NuttX, 1534however, this is not treated as part of NuttX and may be replaced with a 1535different application directory. For the most part, the application 1536directory is treated like any other build directory in the `Makefile` script. 1537However, as a convenience, the following targets are included to support 1538housekeeping functions in the user application directory from the NuttX 1539build directory. 1540 1541 * `apps_clean` 1542 1543 Perform the clean operation only in the user application directory 1544 1545 * `apps_distclean` 1546 1547 Perform the distclean operation only in the user application directory. 1548 The apps/.config file is preserved so that this is not a "full" distclean 1549 but more of a configuration "reset" for the application directory. 1550 1551 * `export` 1552 1553 The export target will package the NuttX libraries and header files into 1554 an exportable package. Caveats: (1) These needs some extension for the KERNEL 1555 build. (2) The logic in tools/mkexport.sh only supports GCC and, for example, 1556 explicitly assumes that the archiver is 'ar' 1557 1558 * `flash` (or `download` : DEPRECATED) 1559 1560 This is a helper target that will rebuild NuttX and flash it to the target 1561 system in one step. The operation of this target depends completely upon 1562 implementation of the FLASH command in the user Make.defs file. It will 1563 generate an error if the FLASH command is not defined. 1564 1565The following targets are used internally by the make logic but can be invoked 1566from the command under certain conditions if necessary. 1567 1568 * `depend` 1569 1570 Create build dependencies. (NOTE: There is currently no support for build 1571 dependencies under Cygwin using Windows-native toolchains.) 1572 1573 * `context` 1574 1575 The context target is invoked on each target build to assure that NuttX is 1576 properly configured. The basic configuration steps include creation of the 1577 the `config.h` and `version.h` header files in the `include/nuttx` directory and 1578 the establishment of symbolic links to configured directories. 1579 1580 * `clean_context` 1581 1582 This is part of the `distclean` target. It removes all of the header files 1583 and symbolic links created by the context target. 1584 1585### Build Options 1586 1587Of course, the value any make variable an be overridden from the make command 1588line. However, there is one particular variable assignment option that may 1589be useful to you: 1590 1591 * `V=1` 1592 1593 This is the build "verbosity flag." If you specify `V=1` on the make command 1594 line, you will see the exact commands used in the build. This can be very 1595 useful when adding new boards or tracking down compile time errors and 1596 warnings (Contributed by Richard Cochran). 1597 1598## Native Windows Build 1599 1600The beginnings of a Windows native build are in place but still not often 1601used as of this writing. The build was functional but because of lack of 1602use may find some issues to be resolved with this build configuration. 1603 1604The windows native build logic initiated if CONFIG_WINDOWS_NATIVE=y is 1605defined in the NuttX configuration file: 1606 1607This build: 1608 1609 - Uses all Windows style paths 1610 - Uses primarily Windows batch commands from cmd.exe, with 1611 - A few extensions from GNUWin32 1612 1613In this build, you cannot use a Cygwin or MSYS shell. Rather the build must 1614be performed in a Windows console window. Here is a better terminal than the 1615standard issue, CMD.exe terminal: ConEmu which can be downloaded from: 1616<https://sourceforge.net/projects/conemu/> or <https://conemu.github.io/>. 1617 1618Build Tools. The build still relies on some Unix-like commands. I use 1619the GNUWin32 tools that can be downloaded from <http://gnuwin32.sourceforge.net/> 1620using the *Download all* selection. Individual packages can be download 1621instead if you know what you are doing and want a faster download (No, I 1622can't tell you which packages you should or should not download). 1623 1624NOTE: It should be possible to use Cygwin or MSYS2 in place of the GNUWin32 1625tools. There are, however, complexities in doing that because those tools 1626depend on the shell environment and use DLLs that are not found (at least 1627not without the correct setup). 1628 1629Host Compiler: I use the MingGW GCC compiler which can be downloaded from 1630<http://www.mingw.org/>. If you are using GNUWin32, then it is recommended 1631the you not install the optional MSYS components as there may be conflicts. 1632 1633Kconfig-frontends: See the section entitled "NuttX Configuration Tool 1634under DOS" for information about installing the `kconfig-frontend` tools to 1635run natively under Windows. 1636 1637This capability should still be considered a work in progress because: 1638 1639 1. It has not been verified on all targets and tools, and 1640 2. it still lacks some of the creature-comforts of the more mature 1641 environments. 1642 1643## Installing GNUWin32 1644 1645 The Windows native build will depend upon a few Unix-like tools that can be 1646 provided either by MSYS or GNUWin32. The GNUWin32 are available from 1647 <http://gnuwin32.sourceforge.net/>. GNUWin32 provides ports of tools with a 1648 GPL or similar open source license to modern MS-Windows (Microsoft Windows 1649 2000 / XP / 2003 / Vista / 2008 / 7). See 1650 <http://gnuwin32.sourceforge.net/packages.html> for a list of all of the tools 1651 available in the GNUWin32 package. 1652 1653 The SourceForge project is located here: 1654 <http://sourceforge.net/projects/gnuwin32/>. The project is still being 1655 actively supported (although some of the Windows ports have gotten very old). 1656 1657 Some commercial toolchains include a subset of the GNUWin32 tools in the 1658 installation. My recommendation is that you download the GNUWin32 tools 1659 directly from the sourceforge.net website so that you will know what you are 1660 using and can reproduce your build environment. 1661 1662 GNUWin32 Installation Steps: 1663 1664 The following steps will download and execute the GNUWin32 installer. 1665 16661. Download `GetGNUWin32-x.x.x.exe` from 1667 <http://sourceforge.net/projects/getgnuwin32/files/>. This is the 1668 installer. The current version as of this writing is 0.6.3. 1669 16702. Run the installer. 1671 16723. Accept the license. 1673 16744. Select the installation directory. My recommendation is the 1675 directory that contains this README file (`<this-directory>`). 1676 16775. After running `GetGNUWin32-0.x.x.exe`, you will have a new directory 1678 `<this-directory>/GetGNUWin32` 1679 1680 Note that the GNUWin32 installer didn't install GNUWin32. Instead, it 1681 installed another, smarter downloader. That downloader is the GNUWin32 1682 package management tool developed by the Open SSL project. 1683 1684 The following steps probably should be performed from inside a DOS shell. 1685 16866. Change to the directory created by `GetGNUWin32-x.x.x.exe` 1687 1688 cd GetGNUWin32 1689 16907. Execute the download.bat script. The download.bat script will download 1691 about 446 packages! Enough to have a very complete Linux-like environment 1692 under the DOS shell. This will take awhile. This step only downloads 1693 the packages and the next step will install the packages. 1694 1695 download 1696 16978. This step will install the downloaded packages. The argument of the 1698 install.bat script is the installation location. C:\gnuwin32 is the 1699 standard install location: 1700 1701 install C:\gnuwin32 1702 1703 **NOTE**: This installation step will install *all* GNUWin32 packages... far 1704 more than you will ever need. If disc space is a problem for you, you might 1705 need to perform a manual installation of the individual ZIP files that you 1706 will find in the `<this directory>/GetGNUWin32/packages` directory. 1707 17089. Make sure that you add the GNUWin32 tools to your path variable: 1709 1710 set PATH=C:\gnuwin32\bin;%PATH% 1711 1712 **WARNING**: Make sure you have `C:\MinGW\bin` in your path before any other 1713 directory that contains `libiconv-2.dll`. Apparently the `as.exe` in some 1714 MinGW distributions are dependent on that DLL, and having an old 1715 version of it in the path somewhere (for example GnuWin32 tools) will 1716 cause as.exe to pick up the older version that doesn't have the entry 1717 point it's looking for. 1718 1719# CYGWIN BUILD PROBLEMS 1720 1721## Performance 1722 1723Build performance under Cygwin is really not so bad, certainly not as good 1724as a Linux build. However, often you will find that the performance is 1725not just bad but terrible. If you are seeing awful performance.. like two 1726or three compilations per second.. the culprit is usually your Windows 1727Anti-Virus protection interfering with the build tool program execution. 1728 1729I use Cygwin quite often and I use Windows Defender. In order to get good 1730build performance, I routinely keep the Windows Defender "Virus & Threat 1731Protections Settings" screen up: I disable "Real-Time Protection" just 1732before entering 'make' then turn "Real-Time Protection" back on when the 1733build completes. With this additional nuisance step, I find that build 1734performance under Cygwin is completely acceptable. 1735 1736## Strange Path Problems 1737 1738If you see strange behavior when building under Cygwin then you may have 1739a problem with your PATH variable. For example, if you see failures to 1740locate files that are clearly present, that may mean that you are using 1741the wrong version of a tool. For example, you may not be using Cygwin's 1742'make' program at /usr/bin/make. Try: 1743 1744 which make 1745 /usr/bin/make 1746 1747When you install some toolchains (such as Yargarto or CodeSourcery tools), 1748they may modify your PATH variable to include a path to their binaries. 1749At that location, they may have GNUWin32 versions of the tools. So you 1750might actually be using a version of make that does not understand Cygwin 1751paths. 1752 1753The solution is either: 1754 1755 1. Edit your PATH to remove the path to the GNUWin32 tools, or 1756 1757 2. Put /usr/local/bin, /usr/bin, and /bin at the front of your path: 1758 1759 export PATH=/usr/local/bin:/usr/bin:/bin:$PATH 1760 1761## Window Native Toolchain Issues 1762 1763There are many popular Windows native toolchains that may be used with NuttX. 1764Examples include CodeSourcery (for Windows), devkitARM, and several vendor- 1765provided toolchains. There are several limitations with using a and Windows 1766based toolchain in a Cygwin environment. The three biggest are: 1767 1768 1. The Windows toolchain cannot follow Cygwin paths. Path conversions are 1769 performed automatically in the Cygwin makefiles using the 'cygpath' utility 1770 but you might easily find some new path problems. If so, check out 'cygpath -w' 1771 1772 2. Windows toolchains cannot follow Cygwin symbolic links. Many symbolic links 1773 are used in NuttX (e.g., include/arch). The make system works around these 1774 problems for the Windows tools by copying directories instead of linking them. 1775 But this can also cause some confusion for you: For example, you may edit 1776 a file in a "linked" directory and find that your changes had no effect. 1777 That is because you are building the copy of the file in the "fake" symbolic 1778 directory. If you use a Windows toolchain, you should get in the habit of 1779 making like this: 1780 1781 make clean_context all 1782 1783 An alias in your .bashrc file might make that less painful. The rebuild 1784 is not a long as you might think because there is no dependency checking 1785 if you are using a native Windows toolchain. That bring us to #3: 1786 1787## General Pre-built Toolchain Issues 1788 1789To continue with the list of "Window Native Toolchain Issues" we can add 1790the following. These, however, are really just issues that you will have 1791if you use any pre-built toolchain (vs. building the NuttX toolchain from 1792the NuttX buildroot package): 1793 1794There may be incompatibilities with header files, libraries, and compiler 1795built-in functions detailed below. For the most part, these issues 1796are handled in the existing make logic. But if you are breaking new ground, 1797then you may encounter these: 1798 1799 1. Header Files. Most pre-built toolchains will build with a foreign C 1800 library (usually newlib, but maybe uClibc or glibc if you are using a 1801 Linux toolchain). This means that the header files from the foreign 1802 C library will be built into the toolchain. So if you `#include <stdio.h>`, 1803 you will get the stdio.h from the incompatible, foreign C library and 1804 not the nuttx `stdio.h` (at `nuttx/include/stdio.h`) that you wanted. 1805 1806 This can cause confusion in the builds and you must always be 1807 sure the `-nostdinc` is included in the `CFLAGS`. That will assure that 1808 you take the include files only from 1809 1810 2. Libraries. What was said above header files applies to libraries. 1811 You do not want to include code from the libraries of any foreign 1812 C libraries built into your toolchain. If this happens you will get 1813 perplexing errors about undefined symbols. To avoid these errors, 1814 you will need to add `-nostdlib` to your `CFLAGS` flags to assure that 1815 you only take code from the NuttX libraries. 1816 1817 This, however, may causes other issues for libraries in the toolchain 1818 that you do want (like `libgcc.a` or `libm.a`). These are special-cased 1819 in most Makefiles, but you could still run into issues of missing 1820 libraries. 1821 1822 3. Built-Ins. Some compilers target a particular operating system. 1823 Many people would, for example, like to use the same toolchain to 1824 develop Linux and NuttX software. Compilers built for other 1825 operating systems may generate incompatible built-in logic and, 1826 for this reason, `-fno-builtin` should also be included in your 1827 C flags 1828 1829 And finally you may not be able to use NXFLAT. 1830 1831 4. NXFLAT. If you use a pre-built toolchain, you will lose all support 1832 for NXFLAT. NXFLAT is a binary format described in 1833 Documentation/NuttXNxFlat.html. It may be possible to build 1834 standalone versions of the NXFLAT tools; there are a few examples 1835 of this in the buildroot repository at <https://bitbucket.org/nuttx/buildroot> 1836 However, it is possible that there could be interoperability issues 1837 with your toolchain since they will be using different versions of 1838 binutils and possibly different ABIs. 1839 1840## Building Original Linux Boards in Cygwin 1841 1842Some default board configurations are set to build under Linux and others 1843to build under Windows with Cygwin. Various default toolchains may also 1844be used in each configuration. It is possible to change the default 1845setup. Here, for example, is what you must do in order to compile a 1846default Linux configuration in the Cygwin environment using the 1847CodeSourcery for Windows toolchain. After instantiating a "canned" 1848NuttX configuration, run the target 'menuconfig' and set the following 1849items: 1850 1851 Build Setup->Build Host Platform->Windows 1852 Build Setup->Windows Build Environment->Cygwin 1853 System Type->Toolchain Selection->CodeSourcery GNU Toolchain under Windows 1854 1855In Windows 7 it may be required to open the Cygwin shell as Administrator 1856("Run As" option, right button) you find errors like "Permission denied". 1857 1858## Recovering from Bad Configurations 1859 1860Many people make the mistake of configuring NuttX with the "canned" 1861configuration and then just typing `make` with disastrous consequences; 1862the build may fail with mysterious, uninterpretable, and irrecoverable 1863build errors. If, for example, you do this with an unmodified Linux 1864configuration in a Windows/Cgwin environment, you will corrupt the 1865build environment. The environment will be corrupted because of POSIX vs 1866Windows path issues and with issues related to symbolic links. If you 1867make the mistake of doing this, the easiest way to recover is to just 1868start over: Do `make distclean` to remove every trace of the corrupted 1869configuration, reconfigure from scratch, and make certain that the set 1870the configuration correctly for your platform before attempting to make 1871again. 1872 1873Just fixing the configuration file after you have instantiated the bad 1874configuration with 'make' is not enough. 1875 1876# DOCUMENTATION 1877 1878Additional information can be found in the Documentation/ directory and 1879also in README files that are scattered throughout the source tree. The 1880documentation is in HTML and can be access by loading the following file 1881into your Web browser: 1882 1883 Documentation/index.html 1884 1885NuttX documentation is also available online at <https://nuttx.apache.org/>. 1886 1887Below is a guide to the available README files in the NuttX source tree: 1888 1889 nuttx/ 1890 | 1891 |- arch/ 1892 | | 1893 | |- arm/ 1894 | | `- src 1895 | | |- common 1896 | | | `- README_lwl_console.txt 1897 | | |- lpc214x 1898 | | | `-README.txt 1899 | | `- stm32l4 1900 | | `- README.txt 1901 | |- renesas/ 1902 | | |- include/ 1903 | | | `-README.txt 1904 | | |- src/ 1905 | | | `-README.txt 1906 | |- x86/ 1907 | | |- include/ 1908 | | | `-README.txt 1909 | | `- src/ 1910 | | `-README.txt 1911 | `- z80/ 1912 | | `- src/ 1913 | | |- z80/README.txt 1914 | | `- z180/README.txt, z180_mmu.txt 1915 | `- README.txt 1916 |- audio/ 1917 | `-README.txt 1918 |- boards/ 1919 | |- arm/ 1920 | | |- a1x/ 1921 | | | `- pcduino-a10/ 1922 | | | `- README.txt 1923 | | |- am335x/ 1924 | | | `- beaglebone-black/ 1925 | | | `- README.txt 1926 | | |- c5471/ 1927 | | | `- c5471evm/ 1928 | | | `- README.txt 1929 | | |- cxd56xx/ 1930 | | | `- spresense/ 1931 | | | `- README.txt 1932 | | |- dm320/ 1933 | | | `- ntosd-dm320/ 1934 | | | |- doc/README.txt 1935 | | | `- README.txt 1936 | | |- efm32/ 1937 | | | |- efm32-g8xx-stk/ 1938 | | | | `- README.txt 1939 | | | |- efm32gg-stk3700/ 1940 | | | | `- README.txt 1941 | | | `- olimex-efm32g880f128-stk/ 1942 | | | `- README.txt 1943 | | |- imx6/ 1944 | | | `- sabre-6quad/ 1945 | | | `- README.txt 1946 | | |- imxrt/ 1947 | | | |- imxrt1050-evk/ 1948 | | | | `- README.txt 1949 | | | |- imxrt1060-evk/ 1950 | | | | `- README.txt 1951 | | | `- teensy-4.x/ 1952 | | | `- README.txt 1953 | | |- kinetis/ 1954 | | | |- freedom-k28f/ 1955 | | | | `- README.txt 1956 | | | |- freedom-k64f/ 1957 | | | | `- README.txt 1958 | | | |- freedom-k66f/ 1959 | | | | `- README.txt 1960 | | | |- kwikstik-k40/ 1961 | | | | `- README.txt 1962 | | | |- teensy-3.x/ 1963 | | | | `- README.txt 1964 | | | |- twr-k60n512/ 1965 | | | | `- README.txt 1966 | | | `- twr-k64f120m/ 1967 | | | `- README.txt 1968 | | |- kl/ 1969 | | | |- freedom-kl25z/ 1970 | | | | `- README.txt 1971 | | | |- freedom-kl26z/ 1972 | | | | `- README.txt 1973 | | | `- teensy-lc/ 1974 | | | `- README.txt 1975 | | |- lc823450/ 1976 | | | `- lc823450-xgevk/ 1977 | | | `- README.txt 1978 | | |- lpc17xx_40xx/ 1979 | | | |- lincoln60/ 1980 | | | | `- README.txt 1981 | | | |- lpc4088-devkit/ 1982 | | | | `- README.txt 1983 | | | |- lpc4088-quickstart/ 1984 | | | | `- README.txt 1985 | | | |- lpcxpresso-lpc1768/ 1986 | | | | `- README.txt 1987 | | | |- lx_cpu/ 1988 | | | | `- README.txt 1989 | | | |- mbed/ 1990 | | | | `- README.txt 1991 | | | |- mcb1700/ 1992 | | | | `- README.txt 1993 | | | |- olimex-lpc1766stk/ 1994 | | | | `- README.txt 1995 | | | |- open1788/ 1996 | | | | `- README.txt 1997 | | | |- pnev5180b/ 1998 | | | | `- README.txt 1999 | | | |- u-blox-c027/ 2000 | | | | `- README.txt 2001 | | | `- zkit-arm-1769/ 2002 | | | `- README.txt 2003 | | |- lpc214x/ 2004 | | | |- mcu123-lpc214x/ 2005 | | | | `- README.txt 2006 | | | `- zp214xpa/ 2007 | | | `- README.txt 2008 | | |- lpc2378/ 2009 | | | `- olimex-lpc2378/ 2010 | | | `- README.txt 2011 | | |- lpc31xx/ 2012 | | | |- ea3131/ 2013 | | | | `- README.txt 2014 | | | |- ea3152/ 2015 | | | | `- README.txt 2016 | | | `- olimex-lpc-h3131/ 2017 | | | `- README.txt 2018 | | |- lpc43xx/ 2019 | | | |- bambino-200e/ 2020 | | | | `- README.txt 2021 | | | |- lpc4330-xplorer/ 2022 | | | | `- README.txt 2023 | | | |- lpc4337-ws/ 2024 | | | | `- README.txt 2025 | | | |- lpc4357-evb/ 2026 | | | | `- README.txt 2027 | | | `- lpc4370-link2/ 2028 | | | `- README.txt 2029 | | |- lpc54xx/ 2030 | | | `- lpcxpresso-lpc54628/ 2031 | | | `- README.txt 2032 | | |- max326xx/ 2033 | | | `- max32660-evsys/ 2034 | | | `- README.txt 2035 | | |- moxart/ 2036 | | | `- moxa/ 2037 | | |- nrf52/ 2038 | | | `- nrf52-generic/ 2039 | | | `- README.txt 2040 | | |- nuc1xx/ 2041 | | | `- nutiny-nuc120/ 2042 | | | `- README.txt 2043 | | |- s32k1xx/ 2044 | | | |- s32k118evb/ 2045 | | | | `- README.txt 2046 | | | |- s32k146evb/ 2047 | | | | `- README.txt 2048 | | | `- s32k148evb/ 2049 | | | `- README.txt 2050 | | |- sam34/ 2051 | | | |- arduino-due/ 2052 | | | | `- README.txt 2053 | | | |- flipnclick-sam3x/ 2054 | | | | `- README.txt 2055 | | | |- sam3u-ek/ 2056 | | | | `- README.txt 2057 | | | |- sam4cmp-db/ 2058 | | | | `- README.txt 2059 | | | |- sam4e-ek/ 2060 | | | | `- README.txt 2061 | | | |- sam4l-xplained/ 2062 | | | | `- README.txt 2063 | | | |- sam4s-xplained/ 2064 | | | | `- README.txt 2065 | | | `- sam4s-xplained-pro/ 2066 | | | `- README.txt 2067 | | |- sama5/ 2068 | | | |- sama5d2-xult/ 2069 | | | | `- README.txt 2070 | | | |- giant-board/ 2071 | | | | `- README.md 2072 | | | |- sama5d3x-ek/ 2073 | | | | `- README.txt 2074 | | | |- sama5d3-xplained/ 2075 | | | | `- README.txt 2076 | | | `- sama5d4-ek/ 2077 | | | `- README.txt 2078 | | |- samd2l2/ 2079 | | | |- arduino-m0/ 2080 | | | | `- README.txt 2081 | | | |- samd20-xplained/ 2082 | | | | `- README.txt 2083 | | | |- samd21-xplained/ 2084 | | | | `- README.txt 2085 | | | `- saml21-xplained/ 2086 | | | `- README.txt 2087 | | |- samd5e5/ 2088 | | | `- metro-m4/ 2089 | | | `- README.txt 2090 | | |- samv7/ 2091 | | | |- same70-qmtech/ 2092 | | | | `- README.txt 2093 | | | |- same70-xplained/ 2094 | | | | `- README.txt 2095 | | | `- samv71-xult/ 2096 | | | `- README.txt 2097 | | |- stm32/ 2098 | | | |- axoloti/ 2099 | | | | `- README.txt 2100 | | | |- b-g474e-dpow1/ 2101 | | | | `- README.txt 2102 | | | |- clicker2-stm32/ 2103 | | | | `- README.txt 2104 | | | |- cloudctrl/ 2105 | | | | `- README.txt 2106 | | | |- emw3162/ 2107 | | | | `- README.txt 2108 | | | |- fire-stm32v2/ 2109 | | | | `- README.txt 2110 | | | |- hymini-stm32v/ 2111 | | | | `- README.txt 2112 | | | |- maple/ 2113 | | | | `- README.txt 2114 | | | |- mikroe-stm32f4/ 2115 | | | | `- README.txt 2116 | | | |- nucleo-f103rb/ 2117 | | | | `- README.txt 2118 | | | |- nucleo-f207zg/ 2119 | | | | `- README.txt 2120 | | | |- nucleo-f302r8/ 2121 | | | | `- README.txt 2122 | | | |- nucleo-f303re/ 2123 | | | | `- README.txt 2124 | | | |- nucleo-f303ze/ 2125 | | | | `- README.txt 2126 | | | |- nucleo-f334r8/ 2127 | | | | `- README.txt 2128 | | | |- nucleo-f410rb/ 2129 | | | | `- README.txt 2130 | | | |- nucleo-f446re/ 2131 | | | | `- README.txt 2132 | | | |- nucleo-f4x1re/ 2133 | | | | `- README.txt 2134 | | | |- nucleo-l152re/ 2135 | | | | `- README.txt 2136 | | | |- olimexino-stm32/ 2137 | | | |- olimex-stm32-e407/ 2138 | | | | `- README.txt 2139 | | | |- olimex-stm32-h405/ 2140 | | | | `- README.txt 2141 | | | |- olimex-stm32-h407/ 2142 | | | | `- README.txt 2143 | | | |- olimex-stm32-p107/ 2144 | | | |- olimex-stm32-p207/ 2145 | | | | `- README.txt 2146 | | | |- olimex-stm32-p407/ 2147 | | | | `- README.txt 2148 | | | |- omnibusf4/ 2149 | | | | `- README.txt 2150 | | | |- photon/ 2151 | | | | `- README.txt 2152 | | | |- shenzhou/ 2153 | | | | `- README.txt 2154 | | | |- stm32_tiny/ 2155 | | | | `- README.txt 2156 | | | |- stm3210e-eval/ 2157 | | | | `- README.txt 2158 | | | |- stm3220g-eval/ 2159 | | | | `- README.txt 2160 | | | |- stm3240g-eval/ 2161 | | | | `- README.txt 2162 | | | |- stm32butterfly2/ 2163 | | | |- stm32f103-minimum/ 2164 | | | | `- README.txt 2165 | | | |- stm32f334-disco/ 2166 | | | | `- README.txt 2167 | | | |- stm32f3discovery/ 2168 | | | | `- README.txt 2169 | | | |- stm32f411e-disco/ 2170 | | | | `- README.txt 2171 | | | |- stm32f429i-disco/ 2172 | | | | `- README.txt 2173 | | | |- stm32f4discovery/ 2174 | | | | `- README.txt 2175 | | | |- stm32ldiscovery/ 2176 | | | | `- README.txt 2177 | | | |- stm32vldiscovery/ 2178 | | | | `- README.txt 2179 | | | `- viewtool-stm32f107/ 2180 | | | `- README.txt 2181 | | |- stm32f0l0g0/ 2182 | | | |- b-l072z-lrwan1/ 2183 | | | | `- README.txt 2184 | | | |- nucleo-f072rb/ 2185 | | | | `- README.txt 2186 | | | |- nucleo-f091rc/ 2187 | | | | `- README.txt 2188 | | | |- nucleo-g070rb/ 2189 | | | | `- README.txt 2190 | | | |- nucleo-g071rb/ 2191 | | | | `- README.txt 2192 | | | |- nucleo-l073rz/ 2193 | | | | `- README.txt 2194 | | | |- stm32f051-discovery/ 2195 | | | | `- README.txt 2196 | | | `- stm32f072-discovery/ 2197 | | | `- README.txt 2198 | | |- stm32f7/ 2199 | | | |- nucleo-144/ 2200 | | | | `- README.txt 2201 | | | |- stm32f746g-disco/ 2202 | | | | |- configs/fb/README.txt 2203 | | | | |- configs/nxdemo/README.txt 2204 | | | | |- configs/nxterm/README.txt 2205 | | | | `- README.txt 2206 | | | |- stm32f746-ws/ 2207 | | | `- stm32f769i-disco/ 2208 | | | `- README.txt 2209 | | |- stm32h7/ 2210 | | | `- nucleo-h743zi/ 2211 | | | `- README.txt 2212 | | |- stm32l4/ 2213 | | | |- b-l475e-iot01a/ 2214 | | | | `- README.txt 2215 | | | |- nucleo-l432kc/ 2216 | | | | `- README.txt 2217 | | | |- nucleo-l452re/ 2218 | | | | `- README.txt 2219 | | | |- nucleo-l476rg/ 2220 | | | | `- README.txt 2221 | | | |- nucleo-l496zg/ 2222 | | | | `- README.txt 2223 | | | |- stm32l476-mdk/ 2224 | | | | `- README.txt 2225 | | | |- stm32l476vg-disco/ 2226 | | | | `- README.txt 2227 | | | `- stm32l4r9ai-disco/ 2228 | | | `- README.txt 2229 | | |- str71x/ 2230 | | | `- olimex-strp711/ 2231 | | | `- README.txt 2232 | | |- tiva/ 2233 | | | |- dk-tm4c129x/ 2234 | | | | `- README.txt 2235 | | | |- eagle100/ 2236 | | | | `- README.txt 2237 | | | |- ekk-lm3s9b96/ 2238 | | | | `- README.txt 2239 | | | |- launchxl-cc1310/ 2240 | | | | `- README.txt 2241 | | | |- launchxl-cc1312r1/ 2242 | | | | `- README.txt 2243 | | | |- lm3s6432-s2e/ 2244 | | | | `- README.txt 2245 | | | |- lm3s6965-ek/ 2246 | | | | `- README.txt 2247 | | | |- lm3s8962-ek/ 2248 | | | | `- README.txt 2249 | | | |- lm4f120-launchpad/ 2250 | | | | `- README.txt 2251 | | | |- tm4c123g-launchpad/ 2252 | | | | `- README.txt 2253 | | | `- tm4c1294-launchpad/ 2254 | | | `- README.txt 2255 | | |- tms570/ 2256 | | | |- launchxl-tms57004/ 2257 | | | | `- README.txt 2258 | | | `- tms570ls31x-usb-kit/ 2259 | | | `- README.txt 2260 | | `- xmc4/ 2261 | | `- xmc4500-relax/ 2262 | | `- README.txt 2263 | |- avr/ 2264 | | |- at32uc3/ 2265 | | | `- avr32dev1/ 2266 | | | `- README.txt 2267 | | |- at90usb/ 2268 | | | |- micropendous3/ 2269 | | | | `- README.txt 2270 | | | `- teensy-2.0/ 2271 | | | `- README.txt 2272 | | `- atmega/ 2273 | | |- amber/ 2274 | | | `- README.txt 2275 | | |- arduino-mega2560/ 2276 | | | `- README.txt 2277 | | `- moteino-mega/ 2278 | | `- README.txt 2279 | |- hc/ 2280 | | `- m9s12/ 2281 | | |- demo9s12ne64/ 2282 | | | `- README.txt 2283 | | `- ne64badge/ 2284 | | `- README.txt 2285 | |- mips/ 2286 | | |- pic32mx/ 2287 | | | |- mirtoo/ 2288 | | | | `- README.txt 2289 | | | |- pic32mx7mmb/ 2290 | | | | `- README.txt 2291 | | | |- pic32mx-starterkit/ 2292 | | | | `- README.txt 2293 | | | |- sure-pic32mx/ 2294 | | | | `- README.txt 2295 | | | `- ubw32/ 2296 | | | `- README.txt 2297 | | `-pic32mz/ 2298 | | |- chipkit-wifire/ 2299 | | | `- README.txt 2300 | | |- flipnclick-pic32mz/ 2301 | | | `- README.txt 2302 | | `- pic32mz-starterkit/ 2303 | | `- README.txt 2304 | |- misoc/ 2305 | | `- lm32/ 2306 | | `- misoc/ 2307 | | `- README.txt 2308 | |- or1k/ 2309 | | `- mor1kx/ 2310 | | `- or1k/ 2311 | | `- README.txt 2312 | |- renesas/ 2313 | | |- m16c/ 2314 | | | `- skp16c26/ 2315 | | | `- README.txt 2316 | | `-sh1/ 2317 | | `- us7032evb1/ 2318 | | `- README.txt 2319 | |- risc-v/ 2320 | |- sim/ 2321 | | `- sim/ 2322 | | `- sim/ 2323 | | |- include/README.txt 2324 | | `- README.txt 2325 | |- x86/ 2326 | | `- qemu/ 2327 | | `- qemu-i486/ 2328 | | `- README.txt 2329 | |- xtensa/ 2330 | | `- esp32/ 2331 | | `- esp32-core/ 2332 | | `- README.txt 2333 | |- z16/ 2334 | | `- z16f/ 2335 | | `- z16f2800100zcog/ 2336 | | |- configs/nsh/README.txt 2337 | | |- configs/ostest/README.txt 2338 | | |- configs/pashello/README.txt 2339 | | `- README.txt 2340 | |- z80/ 2341 | | |- ez80/ 2342 | | | |- ez80f910200kitg/ 2343 | | | | |- configs/ostest/README.txt 2344 | | | | `- README.txt 2345 | | | |- ez80f910200zco/ 2346 | | | | |- configs/dhcpd/README.txt 2347 | | | | |- configs/httpd/README.txt 2348 | | | | |- configs/nettest/README.txt 2349 | | | | |- configs/nsh/README.txt 2350 | | | | |- configs/poll/README.txt 2351 | | | | `- README.txt 2352 | | | |- makerlisp/ 2353 | | | | |- configs/nsh_flash/README.txt 2354 | | | | |- configs/nsh_ram/README.txt 2355 | | | | |- configs/sdboot/README.txt 2356 | | | | `- README.txt 2357 | | | `- z80x/ 2358 | | | |- configs/nsh_flash/README.txt 2359 | | | |- configs/nsh_ram/README.txt 2360 | | | |- configs/sdboot/README.txt 2361 | | | `- README.txt 2362 | | |- z180/ 2363 | | | `- p112/ 2364 | | | `- README.txt 2365 | | |- z8/ 2366 | | | |- z8encore000zco/ 2367 | | | | |- configs/ostest/README.txt 2368 | | | | `- README.txt 2369 | | | `- z8f64200100kit/ 2370 | | | |- configs/ostest/README.txt 2371 | | | `- README.txt 2372 | | `- z80/ 2373 | | `- z80sim/ 2374 | | `- README.txt 2375 | `-README.txt 2376 |- drivers/ 2377 | |- eeprom/ 2378 | | `- README.txt 2379 | |- lcd/ 2380 | | | README.txt 2381 | | `- pcf8574_lcd_backpack_readme.txt 2382 | |- mtd/ 2383 | | `- README.txt 2384 | |- sensors/ 2385 | | `- README.txt 2386 | |- syslog/ 2387 | | `- README.txt 2388 | `- README.txt 2389 |- fs/ 2390 | |- binfs/ 2391 | | `- README.txt 2392 | |- cromfs/ 2393 | | `- README.txt 2394 | |- mmap/ 2395 | | `- README.txt 2396 | |- nxffs/ 2397 | | `- README.txt 2398 | |- smartfs/ 2399 | | `- README.txt 2400 | |- procfs/ 2401 | | `- README.txt 2402 | |- spiffs/ 2403 | | `- README.md 2404 | `- unionfs/ 2405 | `- README.txt 2406 |- graphics/ 2407 | `- README.txt 2408 |- libs/ 2409 | |- README.txt 2410 | |- libc/ 2411 | | |- zoneinfo 2412 | | | `- README.txt 2413 | | `- README.txt 2414 | |- libdsp/ 2415 | | `- README.txt 2416 | |- libnx/ 2417 | | |- nxfongs 2418 | | | `- README.txt 2419 | | `- README.txt 2420 | |- libxx/ 2421 | `- README.txt 2422 |- mm/ 2423 | |- shm/ 2424 | | `- README.txt 2425 | `- README.txt 2426 |- net/ 2427 | |- sixlowpan 2428 | | `- README.txt 2429 | `- README.txt 2430 |- pass1/ 2431 | `- README.txt 2432 |- syscall/ 2433 | `- README.txt 2434 `- tools/ 2435 `- README.txt 2436 2437Below is a guide to the available README files in the semi-optional apps/ 2438source tree: 2439 2440 apps/ 2441 |- examples/ 2442 | |- bastest/README.txt 2443 | |- json/README.txt 2444 | |- pashello/README.txt 2445 | `- README.txt 2446 |- gpsutils/ 2447 | `- minmea/README.txt 2448 |- graphics/ 2449 | |- tiff/README.txt 2450 | `- traveler/tools/tcledit/README.txt 2451 |- interpreters/ 2452 | |- bas/ 2453 | | `- README.txt 2454 | |- ficl/ 2455 | | `- README.txt 2456 | `- README.txt 2457 |- modbus/ 2458 | `- README.txt 2459 |- netutils/ 2460 | |- discover/ 2461 | | `- README.txt 2462 | |- ftpc/ 2463 | | `- README.txt 2464 | |- json/ 2465 | | `- README.txt 2466 | |- telnetd/ 2467 | | `- README.txt 2468 | `- README.txt 2469 |- nshlib/ 2470 | `- README.txt 2471 |- NxWidgets/ 2472 | `- README.txt 2473 |- system/ 2474 | |- cdcacm/ 2475 | | `- README.txt 2476 | |- i2c/ 2477 | | `- README.txt 2478 | |- inifile/ 2479 | | `- README.txt 2480 | |- install/ 2481 | | `- README.txt 2482 | |- nsh/ 2483 | | `- README.txt 2484 | |- nxplayer/ 2485 | | `- README.txt 2486 | |- psmq/ 2487 | | `- README.txt 2488 | |- symtab/ 2489 | | `- README.txt 2490 | |- termcurses/ 2491 | | `- README.txt 2492 | |- usbmsc/ 2493 | | `- README.txt 2494 | `- zmodem/ 2495 | `- README.txt 2496 `- wireless 2497 |- bluetooth/ 2498 | `- btsak/ 2499 | `- README.txt 2500 `- ieee802154 2501 `- i8sak/ 2502 `- README.txt 2503 2504Additional README.txt files in the other, related repositories: 2505 2506 NxWidgets/ 2507 |- Doxygen 2508 | `- README.txt 2509 |- tools 2510 | `- README.txt 2511 |- UnitTests 2512 | `- README.txt 2513 `- README.txt 2514 2515 buildroot/ 2516 `- README.txt 2517 2518 tools/ 2519 `- README.txt 2520 2521 uClibc++/ 2522 `- README.txt 2523