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