diff --git a/Documentation/components/tools/abi_check.rst b/Documentation/components/tools/abi_check.rst new file mode 100644 index 00000000000..422aaec38de --- /dev/null +++ b/Documentation/components/tools/abi_check.rst @@ -0,0 +1,75 @@ +================ +``abi_check.py`` +================ + +``abi_check.py`` is a Python tool for checking binary compatibility based on +DWARF debug information. + +It supports three related workflows: + +1. Given one or more static libraries (``.a``) and an ELF file, collect the + undefined (external) symbols referenced by the libraries, locate those + functions in the ELF file, and write their function signatures to a JSON + file. +2. Generate two JSON files from two different ELF files (for example, an old + build and a new build), and compare the signatures of functions with the + same name (return type, parameters, and for structs also size, member + offsets, member types, etc.). +3. Given a single ELF file, detect structs with the same name but different + members. + +Prerequisites: + +- Python 3 +- ``pyelftools`` (used to read ELF/DWARF) +- ``ar`` (used to extract object files from ``.a`` archives) +- ``pahole`` (only for ``--struct_check``) + +.. note:: + + Although the help text mentions ``.so``, the current implementation uses + ``ar x`` on each ``--lib`` input, so it expects ``.a`` archives. + +Help message:: + + $ python3 tools/abi_check.py -h + usage: abi_check.py [-h] [-a LIB [LIB ...]] [-e ELF] [-c] [-d] [-j JSON] [-s] + [-i INPUT_JSON INPUT_JSON] + + This tool is used to check the binary compatibility of static libraries and has the following features: + 1. The input consists of multiple static libraries and an ELF file. The tool searches + for external APIs used by the static libraries, then locates these API function signatures + in the ELF file, and outputs the results as a JSON file. + 2. Using the first feature, with the static libraries unchanged, + the tool can take a new ELF file and an old ELF file as input, output two JSON files, + and compare the function signatures of functions with the same name in the two JSON files. + The comparison includes return values, parameters, and if they are structures, + it also compares the structure size, member offsets, member types, etc. + 3.When the input is a single ELF file, the tool can check if structures with the same name have different members. + + options: + -h, --help show this help message and exit + -a LIB [LIB ...], --lib LIB [LIB ...] + Path to liba.so or lib.a + -e ELF, --elf ELF Path to elf file + -c, --check If the static library contains debug information, + try to find the function in the static library, + and output the result to lib_ file + -d, --dump Dump result + -j JSON, --json JSON Save result to json file + -s, --struct_check Dump struct different + -i INPUT_JSON INPUT_JSON, --input_json INPUT_JSON INPUT_JSON + Diff two json files + +Examples:: + + # 1) Extract signatures for external APIs referenced by one or more archives + $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx -j out.json + + # 2) Compare signatures across two ELF files + $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_old -j old.json + $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_new -j new.json + $ python3 tools/abi_check.py -i old.json new.json + + # 3) Find struct definition mismatches within a single ELF + $ python3 tools/abi_check.py -e nuttx -s diff --git a/Documentation/components/tools/bdf-convert.rst b/Documentation/components/tools/bdf-convert.rst new file mode 100644 index 00000000000..edd541a6b11 --- /dev/null +++ b/Documentation/components/tools/bdf-convert.rst @@ -0,0 +1,137 @@ +================= +``bdf-convert.c`` +================= + +This C file is used to build the bdf-converter program. The bdf-converter +program can be used to convert fonts in Bitmap Distribution Format (BDF) +into fonts that can be used in the NX graphics system. + +Below are general instructions for creating and installing a new font +in the NX graphic system: + +1. Locate a font in BDF format, +2. Use the bdf-converter program to convert the BDF font to the NuttX + font format. This will result in a C header file containing + definitions. That header file should be installed at, for example, + libnx/nxfonts/nxfonts_myfont.h. + +Create a new NuttX configuration variable. For example, suppose +you define the following variable: CONFIG_NXFONT_MYFONT. Then +you would need to: + +3. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file. + +A font ID number has to be assigned for each new font. The font ID +is defined in the file include/nuttx/nx/nxfonts.h. Those definitions +have to be extended to support your new font. Look at how the font ID +enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for your +new font in a similar fashion: + +4. include/nuttx/nx/nxfonts.h. Add your new font as a possible system + default font:: + + #if defined(CONFIG_NXFONT_SANS23X27) + # define NXFONT_DEFAULT FONTID_SANS23X27 + #elif defined(CONFIG_NXFONT_MYFONT) + # define NXFONT_DEFAULT FONTID_MYFONT + #endif + +Then define the actual font ID. Make sure that the font ID value +is unique:: + + enum nx_fontid_e + { + FONTID_DEFAULT = 0 /* The default font */ + #ifdef CONFIG_NXFONT_SANS23X27 + , FONTID_SANS23X27 = 1 /* The 23x27 sans serif font */ + #endif + #ifdef CONFIG_NXFONT_MYFONT + , FONTID_MYFONT = 2 /* My shiny, new font */ + #endif + ... + +Now add the font to the NX build system. There are several files that +you have to modify to do this. Look how the build system uses the +font CONFIG_NXFONT_SANS23X27 for examples: + +5. nuttx/graphics/Makefile. This file needs logic to auto-generate + a C source file from the header file that you generated with the + the bdf-converter program. Notice NXFONTS_FONTID=2; this must be + set to the same font ID value that you defined in the + include/nuttx/nx/nxfonts.h file:: + + genfontsources: + ifeq ($(CONFIG_NXFONT_SANS23X27),y) + @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS) + endif + ifeq ($(CONFIG_NXFONT_MYFONT),y) + @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS) + endif + +6. nuttx/libnx/nxfonts/Make.defs. Set the make variable NXFSET_CSRCS. + NXFSET_CSRCS determines the name of the font C file to build when + NXFONTS_FONTID=2:: + + ifeq ($(CONFIG_NXFONT_SANS23X27),y) + NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c + endif + ifeq ($(CONFIG_NXFONT_MYFONT),y) + NXFSET_CSRCS += nxfonts_bitmaps_myfont.c + endif + +7. nuttx/libnx/nxfonts/Makefile.sources. This is the Makefile used + in step 5 that will actually generate the font C file. So, given + your NXFONTS_FONTID=2, it needs to determine a prefix to use for + auto-generated variable and function names and (again) the name of + the auto-generated file to create (this must be the same name that + was used in nuttx/libnx/nxfonts/Make.defs):: + + ifeq ($(NXFONTS_FONTID),1) + NXFONTS_PREFIX := g_sans23x27_ + GEN_CSRC = nxfonts_bitmaps_sans23x27.c + endif + ifeq ($(NXFONTS_FONTID),2) + NXFONTS_PREFIX := g_myfont_ + GEN_CSRC = nxfonts_bitmaps_myfont.c + endif + +8. graphics/libnx/nxfonts_bitmaps.c. This is the file that contains + the generic font structures. It is used as a "template" file by + nuttx/libnx/nxfonts/Makefile.sources to create your customized + font data set:: + + #if NXFONTS_FONTID == 1 + # include "nxfonts_sans23x27.h" + #elif NXFONTS_FONTID == 2 + # include "nxfonts_myfont.h" + #else + # error "No font ID specified" + #endif + + Where nxfonts_myfont.h is the NuttX font file that we generated in + step 2 using the bdf-converter tool. + +9. libnx/nxfonts/nxfonts_getfont.c. Finally, we need to extend the + logic that does the run-time font lookups so that can find our new + font. The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid). + The new font information needs to be added to data structures used by + that function:: + + #ifdef CONFIG_NXFONT_SANS23X27 + extern const struct nx_fontpackage_s g_sans23x27_package; + #endif + #ifdef CONFIG_NXFONT_MYFONT + extern const struct nx_fontpackage_s g_myfont_package; + #endif + + static FAR const struct nx_fontpackage_s *g_fontpackages[] = + { + #ifdef CONFIG_NXFONT_SANS23X27 + &g_sans23x27_package, + #endif + #ifdef CONFIG_NXFONT_MYFONT + &g_myfont_package, + #endif + NULL + }; + diff --git a/Documentation/components/tools/checkkconfig.rst b/Documentation/components/tools/checkkconfig.rst new file mode 100644 index 00000000000..1ec768f9064 --- /dev/null +++ b/Documentation/components/tools/checkkconfig.rst @@ -0,0 +1,43 @@ +=================== +``checkkconfig.py`` +=================== + +``checkkconfig.py`` is a Python script that simulates the effects of modifying a CONFIG item. +It can be used to check whether my config changes are what I expected. + +Help message:: + + $ tools/checkkconfig.py -h + usage: checkkconfig.py [-h] -f FILE (-s CONFIG VALUE | -d DIFF) + + optional arguments: + -h, --help show this help message and exit + -f FILE, --file FILE Path to the input defconfig file + -s CONFIG_XXX VALUE, --single CONFIG VALUE + Analyze single change: CONFIG_NAME y/m/n + -d DIFF, --diff DIFF Analyze changes from diff file + + example: ./tools/checkkconfig.py -f defconfig -s ELF n + + outputs: + Change report for ELF=n + Config Option Old New + ---------------------------------------------------------------------- + BINFMT_LOADABLE y n + ELF y n + ELF_STACKSIZE 8192 + LIBC_ARCH_ELF y n + LIBC_MODLIB y n + MODLIB_ALIGN_LOG2 2 + MODLIB_BUFFERINCR 32 + MODLIB_BUFFERSIZE 32 + MODLIB_MAXDEPEND 2 + MODLIB_RELOCATION_BUFFERCOUNT 256 + MODLIB_SYMBOL_CACHECOUNT 256 + +As we can see, we can clearly know that +if I turn off ELF in defconfig at this time, +it will bring about the following configuration linkage changes + +It can also parse diff files, which can be used to check the changes of multiple +configs. diff --git a/Documentation/components/tools/checkpatch.rst b/Documentation/components/tools/checkpatch.rst new file mode 100644 index 00000000000..4f907bfac89 --- /dev/null +++ b/Documentation/components/tools/checkpatch.rst @@ -0,0 +1,29 @@ +================= +``checkpatch.sh`` +================= + +``checkpatch.sh`` is a bash script that makes use of ``nxstyle`` and +``codespell`` tools to format patches and ensure that files conform to NuttX +coding standard. It is used in NuttX's GitHub CI. + +Help message: + +.. code:: console + + $ tools/checkpatch.sh -h + USAGE: tools/checkpatch.sh [options] [list|-] + + Options: + -h + -c spell check with codespell (install with: pip install codespell) + -u encoding check with cvt2utf (install with: pip install cvt2utf) + -r range check only (coupled with -p or -g) + -p (default) + -m Check commit message (coupled with -g) + -g + -f + -x format supported files (only .py, requires: pip install black) + - read standard input mainly used by git pre-commit hook as below: + git diff --cached | ./tools/checkpatch.sh - + Where a is any syntax supported by git for specifying git revision, see GITREVISIONS(7) + Where a is a space separated list of patch file names or wildcard. or *.patch diff --git a/Documentation/components/tools/cmpconfig.rst b/Documentation/components/tools/cmpconfig.rst new file mode 100644 index 00000000000..b0eba75ad6e --- /dev/null +++ b/Documentation/components/tools/cmpconfig.rst @@ -0,0 +1,6 @@ +=============== +``cmpconfig.c`` +=============== + +This C file can be used to build a utility for comparing two NuttX configuration +files. diff --git a/Documentation/components/tools/configure-x.rst b/Documentation/components/tools/configure-x.rst new file mode 100644 index 00000000000..5f9e034c6b8 --- /dev/null +++ b/Documentation/components/tools/configure-x.rst @@ -0,0 +1,29 @@ +====================================================================================== +``configure.sh``, ``configure.bat``, ``configure.c``, ``cfgparser.c``, ``cfgparser.h`` +====================================================================================== + +``configure.sh`` is a bash script that is used to configure NuttX for a given +target board in a environment that supports POSIX paths (Linux, Cygwin, macOS, +or similar). See :doc:`/components/boards` or +Documentation/NuttXPortingGuide.html for a description of how to configure NuttX +with this script. + +configure.c, cfgparser.c, and cfgparser.h can be used to build a work-alike +program as a replacement for configure.sh. This work-alike program would be +used in environments that do not support Bash scripting (such as the Windows +native environment). + +configure.bat is a small Windows batch file that can be used as a replacement +for configure.sh in a Windows native environment. configure.bat is actually +just a thin layer that executes configure.exe if it is available. If +configure.exe is not available, then configure.bat will attempt to build it +first. + +In order to build configure.exe from configure.c in the Windows native +environment, two assumptions are made: + +1) You have installed the MinGW GCC toolchain. This toolchain can be + downloaded from http://www.mingw.org/. It is recommended that you not + install the optional MSYS components as there may be conflicts. +2) That path to the bin/ directory containing mingw-gcc.exe must be + included in the PATH variable. diff --git a/Documentation/components/tools/convert-comments.rst b/Documentation/components/tools/convert-comments.rst new file mode 100644 index 00000000000..716b6050abe --- /dev/null +++ b/Documentation/components/tools/convert-comments.rst @@ -0,0 +1,9 @@ +====================== +``convert-comments.c`` +====================== + +Convert C++-style comments to C89 C-style comments. Usage: + +.. code:: console + + $ convert-comments diff --git a/Documentation/components/tools/define.rst b/Documentation/components/tools/define.rst new file mode 100644 index 00000000000..ca6b093c2b5 --- /dev/null +++ b/Documentation/components/tools/define.rst @@ -0,0 +1,11 @@ +============================= +``define.sh``, ``define.bat`` +============================= + +Different compilers have different conventions for specifying pre- +processor definitions on the compiler command line. This bash +script allows the build system to create command line definitions +without concern for the particular compiler in use. + +The define.bat script is a counterpart for use in the native Windows +build. diff --git a/Documentation/components/tools/detab.rst b/Documentation/components/tools/detab.rst new file mode 100644 index 00000000000..d6037821592 --- /dev/null +++ b/Documentation/components/tools/detab.rst @@ -0,0 +1,11 @@ +=========== +``detab.c`` +=========== + +Convert tabs to spaces in a file. Usage: + +.. code:: console + + $ detab [-4] + +Default ```` tab size is 8 spaces; ``-4`` selects 4 space tab size. diff --git a/Documentation/components/tools/discover.rst b/Documentation/components/tools/discover.rst new file mode 100644 index 00000000000..da90a860b7a --- /dev/null +++ b/Documentation/components/tools/discover.rst @@ -0,0 +1,6 @@ +=============== +``discover.py`` +=============== + +Example script for discovering devices in the local network. It is the counter +part to :doc:`/applications/netutils/discover/index`. diff --git a/Documentation/components/tools/flash_writer.rst b/Documentation/components/tools/flash_writer.rst new file mode 100644 index 00000000000..4630728dee5 --- /dev/null +++ b/Documentation/components/tools/flash_writer.rst @@ -0,0 +1,13 @@ +=================== +``flash_writer.py`` +=================== + +This flash writer is using the xmodem for firmware transfer on +boards based on cxd56 chip (Ex. Spresense). This tool depends on +the xmodem package (https://pypi.org/project/xmodem/). + +For flashing the ``.spk`` image to the board please use: + +.. code:: console + + $ tools/flash_writer.py -s -c /dev/ttyUSB0 -d -b 115200 -n nuttx.spk diff --git a/Documentation/components/tools/gencromfs.rst b/Documentation/components/tools/gencromfs.rst new file mode 100644 index 00000000000..b17e1cdd3e5 --- /dev/null +++ b/Documentation/components/tools/gencromfs.rst @@ -0,0 +1,18 @@ +=============== +``gencromfs.c`` +=============== + +This is a C program that is used to generate CROMFS file system images. +Usage is simple: + +.. code:: console + + $ gencromfs + +Where: + +* ```` is the path to the directory will be at the root of the new + CROMFS file system image. + +* ```` the name of the generated, output C file. This file must be + compiled in order to generate the binary CROMFS file system image. diff --git a/Documentation/components/tools/ide_exporter.rst b/Documentation/components/tools/ide_exporter.rst new file mode 100644 index 00000000000..9c97fdee5ef --- /dev/null +++ b/Documentation/components/tools/ide_exporter.rst @@ -0,0 +1,114 @@ +=================== +``ide_exporter.py`` +=================== + +This Python script will help to create NuttX project in the IAR and +uVision IDEs. These are few simple the steps to export the IDE +workspaces. + +1) Start the NuttX build from the Cygwin command line before trying to + create your project by running:: + + make V=1 |& tee build_log + + This is necessary to certain auto-generated files and directories that + will be needed. This will provide the build log to construct the IDE + project also. + +2) Export the IDE project base on that make log. The script usage: + + usage: ide_exporter.py [-h] [-v] [-o OUT_DIR] [-d] build_log {iar,uvision_armcc,uvision_gcc} template_dir + + positional arguments:: + + build_log Log file from make V=1 + {iar,uvision_armcc,uvision_gcc} + The target IDE: iar, uvision_gcc, (uvision_armcc is experimental) + template_dir Directory that contains IDEs template projects + + optional arguments:: + + -h, --help show this help message and exit + -v, --version show program's version number and exit + -o OUT_DIR, --output OUT_DIR + Output directory + -d, --dump Dump project structure tree + + Example:: + + cd nuttx + make V=1 |& tee build_log + + ./tools/ide_exporter.py makelog_f2nsh_c iar ./boards////ide/template/iar -o ./boards////ide/nsh/iar + + or:: + + ./tools/ide_exporter.py makelog_f2nsh_c uvision_gcc ./boards////ide/template/uvision_gcc/ -o ./boards////ide/nsh/uvision + +3) Limitations: + + - IAR supports C only. Iar C++ does not compatible with g++ so disable + C++ if you want to use IAR. + - uvision_armcc : nuttx asm (inline and .asm) can't be compiled with + armcc so do not use this option. + - uvision_gcc : uvision project that uses gcc. Need to specify path to + gnu toolchain. + In uVison menu, select:: + + Project/Manage/Project Items.../FolderExtension/Use GCC compiler/ PreFix, Folder + +4) Template projects' constrains: + + - mcu, core, link script shall be configured in template project + - Templates' name are fixed: + + - template_nuttx.eww : IAR nuttx workspace template + - template_nuttx_lib.ewp : IAR nuttx library project template + - template_nuttx_main.ewp : IAR nuttx main project template + - template_nuttx.uvmpw : uVision workspace + - template_nuttx_lib.uvproj : uVision library project + - template_nuttx_main.uvproj : uVision main project + - iar: + + - Library option shall be set to 'None' so that IAR could use nuttx + libc + - __ASSEMBLY__ symbol shall be defined in assembler + + - uVision_gcc: + + - There should be one fake .S file in projects that has been defined + __ASSEMBLY__ in assembler. + - In Option/CC tab : disable warning + - In Option/CC tab : select Compile thump code (or Misc control = + -mthumb) + - template_nuttx_lib.uvproj shall add 'Post build action' to copy .a + file to .\lib + - template_nuttx_main.uvproj Linker: + + - Select 'Do not use Standard System Startup Files' and 'Do not + use Standard System Libraries' + - Do not select 'Use Math libraries' + - Misc control = --entry=__start + +5) How to create template for other configurations: + + 1) uVision with gcc toolchain: + + - Copy 3 uVision project files + - Select the MCU for main and lib project + - Correct the path to ld script if needed + + 2) iar: + + - Check if the arch supports IAR (only armv7-m is support IAR + now) + - Select the MCU for main and lib project + - Add new ld script file for IAR + +.. note:: + + Due to bit rot, the template files for the stm3220g-eval and for the + stm32f429-disco have been removed from the NuttX repository. For reference, + they can be found in the Obsoleted repository at + Obsoleted/stm32f429i_disco/ltcd/template and at + Obsoleted/stm3220g-eval/template. diff --git a/Documentation/components/tools/incdir.rst b/Documentation/components/tools/incdir.rst new file mode 100644 index 00000000000..3c5055871af --- /dev/null +++ b/Documentation/components/tools/incdir.rst @@ -0,0 +1,14 @@ +=========================================== +``incdir.sh``, ``incdir.bat``, ``incdir.c`` +=========================================== + +Different compilers have different conventions for specifying lists +of include file paths on the compiler command line. This incdir.sh +bash script allows the build system to create include file paths without +concern for the particular compiler in use. + +The incdir.bat script is a counterpart for use in the native Windows +build. However, there is currently only one compiler supported in +that context: MinGW-GCC. + +incdir.c is a higher performance version of incdir.sh, converted to C. diff --git a/Documentation/components/tools/indent.rst b/Documentation/components/tools/indent.rst new file mode 100644 index 00000000000..61c75b112de --- /dev/null +++ b/Documentation/components/tools/indent.rst @@ -0,0 +1,68 @@ +============= +``indent.sh`` +============= + +This script can be used to indent .c and .h files in a manner similar +to the NuttX coding style. It doesn't do a really good job, however +(see below and the comments at the top of the indent.sh file). + +USAGE:: + + tools/indent.sh [-d] [-p] -o + tools/indent.sh [-d] [-p] + tools/indent.sh [-d] -h + +Where:: + + - + A single, unformatted input file + - + A list of unformatted input files that will be reformatted in place. + -o + Write the single, reformatted to . + will not be modified. + -d + Enable script debug + -p + Comments are pre-formatted. Do not reformat. + -h + Show this help message and exit + +The conversions make by the indent.sh script differs from the NuttX coding +style in that: + +1. The coding standard requires that the trailing ``*/`` of a multi-line + comment be on a separate line. By default, indent.sh will put the + final ``*/`` on the same line as the last comment text. If your C file + already has properly formatted comments then using the ``-p`` option will + eliminate that bad behavior + +2. If your source file has highly formatted comments containing things + such as tables or lists, then use the -p option to preserve those + pre-formatted comments. + +3. I usually align things vertically (like '=' in assignments), + +4. indent.sh puts a bogus blank line at the top of the file, + +5. I don't like the way it handles nested conditional compilation + intermixed with code. I prefer the preprocessor conditional tests + be all right justified in that case. + +6. I also indent brackets differently on structures than does this script. + +7. I normally use no spaces in casts. indent.sh adds spaces in casts like + ``(FAR void *)&foo`` becomes ``(FAR void *) & foo``. + +8. When used with header files, the initial idempotence conditional test + causes all preprocessor directives to be indented in the file. So for + header files, you will need to substitute "^# " with "#" in the + converted header file. + +You will manually need to check for the issues listed above after +performing the conversions. nxstyle.c provides a good test that will +catch most of the indent.sh screw-ups. Together, they do a pretty good +job of formatting. + +See also nxstyle.c and uncrustify.cfg + diff --git a/Documentation/components/tools/index.rst b/Documentation/components/tools/index.rst index 8350d94f44f..ee6e5cd65c9 100644 --- a/Documentation/components/tools/index.rst +++ b/Documentation/components/tools/index.rst @@ -5,1342 +5,9 @@ Host Tools This page discusses the ``tools/`` directory containing miscellaneous scripts and host C programs that are important parts of the NuttX build system: -.. contents:: - :local: - :backlinks: entry - :depth: 2 - -abi_check.py ------------- - -``abi_check.py`` is a Python tool for checking binary compatibility based on -DWARF debug information. - -It supports three related workflows: - -1. Given one or more static libraries (``.a``) and an ELF file, collect the - undefined (external) symbols referenced by the libraries, locate those - functions in the ELF file, and write their function signatures to a JSON - file. -2. Generate two JSON files from two different ELF files (for example, an old - build and a new build), and compare the signatures of functions with the - same name (return type, parameters, and for structs also size, member - offsets, member types, etc.). -3. Given a single ELF file, detect structs with the same name but different - members. - -Prerequisites: - -- Python 3 -- ``pyelftools`` (used to read ELF/DWARF) -- ``ar`` (used to extract object files from ``.a`` archives) -- ``pahole`` (only for ``--struct_check``) - -.. note:: - - Although the help text mentions ``.so``, the current implementation uses - ``ar x`` on each ``--lib`` input, so it expects ``.a`` archives. - -Help message:: - - $ python3 tools/abi_check.py -h - usage: abi_check.py [-h] [-a LIB [LIB ...]] [-e ELF] [-c] [-d] [-j JSON] [-s] - [-i INPUT_JSON INPUT_JSON] - - This tool is used to check the binary compatibility of static libraries and has the following features: - 1. The input consists of multiple static libraries and an ELF file. The tool searches - for external APIs used by the static libraries, then locates these API function signatures - in the ELF file, and outputs the results as a JSON file. - 2. Using the first feature, with the static libraries unchanged, - the tool can take a new ELF file and an old ELF file as input, output two JSON files, - and compare the function signatures of functions with the same name in the two JSON files. - The comparison includes return values, parameters, and if they are structures, - it also compares the structure size, member offsets, member types, etc. - 3.When the input is a single ELF file, the tool can check if structures with the same name have different members. - - options: - -h, --help show this help message and exit - -a LIB [LIB ...], --lib LIB [LIB ...] - Path to liba.so or lib.a - -e ELF, --elf ELF Path to elf file - -c, --check If the static library contains debug information, - try to find the function in the static library, - and output the result to lib_ file - -d, --dump Dump result - -j JSON, --json JSON Save result to json file - -s, --struct_check Dump struct different - -i INPUT_JSON INPUT_JSON, --input_json INPUT_JSON INPUT_JSON - Diff two json files - -Examples:: - - # 1) Extract signatures for external APIs referenced by one or more archives - $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx -j out.json - - # 2) Compare signatures across two ELF files - $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_old -j old.json - $ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_new -j new.json - $ python3 tools/abi_check.py -i old.json new.json - - # 3) Find struct definition mismatches within a single ELF - $ python3 tools/abi_check.py -e nuttx -s - -cmpconfig.c ------------ - -This C file can be used to build a utility for comparing two NuttX -configuration files. - -checkkconfig.py ---------------- - -``checkkconfig.py`` is a Python script that simulates the effects of modifying a CONFIG item. -It can be used to check whether my config changes are what I expected. - -Help message:: - - $ tools/checkkconfig.py -h - usage: checkkconfig.py [-h] -f FILE (-s CONFIG VALUE | -d DIFF) - - optional arguments: - -h, --help show this help message and exit - -f FILE, --file FILE Path to the input defconfig file - -s CONFIG_XXX VALUE, --single CONFIG VALUE - Analyze single change: CONFIG_NAME y/m/n - -d DIFF, --diff DIFF Analyze changes from diff file - - example: ./tools/checkkconfig.py -f defconfig -s ELF n - - outputs: - Change report for ELF=n - Config Option Old New - ---------------------------------------------------------------------- - BINFMT_LOADABLE y n - ELF y n - ELF_STACKSIZE 8192 - LIBC_ARCH_ELF y n - LIBC_MODLIB y n - MODLIB_ALIGN_LOG2 2 - MODLIB_BUFFERINCR 32 - MODLIB_BUFFERSIZE 32 - MODLIB_MAXDEPEND 2 - MODLIB_RELOCATION_BUFFERCOUNT 256 - MODLIB_SYMBOL_CACHECOUNT 256 - -As we can see, we can clearly know that -if I turn off ELF in defconfig at this time, -it will bring about the following configuration linkage changes - -It can also parse diff files, which can be used to check the changes of multiple configs. - -checkpatch.sh -------------- - -``checkpatch.sh`` is a bash script that make use of nxstyle and codespell tools -to format patches and files conform to NuttX coding standard. For example, -it has been used in NuttX github action PR check build - - -Help message:: - - $ tools/checkpatch.sh -h - USAGE: ./tools/checkpatch.sh [options] [list|-] - - Options: - -h - -c spell check with codespell (install with: pip install codespell) - -u encoding check with cvt2utf (install with: pip install cvt2utf) - -r range check only (coupled with -p or -g) - -p (default) - -m Change-Id check in commit message (coupled with -g) - -g - -f - - read standard input mainly used by git pre-commit hook as below: - git diff --cached | ./tools/checkpatch.sh - - Where a is any syntax supported by git for specifying git revision, see GITREVISIONS(7) - Where a is a space separated list of patch file names or wildcard. or *.patch - -configure.sh configure.bat configure.c, cfgparser.c, and cfgparser.h --------------------------------------------------------------------- - -configure.sh is a bash script that is used to configure NuttX for a given -target board in a environment that supports POSIX paths (Linux, Cygwin, -macOS, or similar). See :doc:`/components/boards` or Documentation/NuttXPortingGuide.html -for a description of how to configure NuttX with this script. - -configure.c, cfgparser.c, and cfgparser.h can be used to build a work-alike -program as a replacement for configure.sh. This work-alike program would be -used in environments that do not support Bash scripting (such as the Windows -native environment). - -configure.bat is a small Windows batch file that can be used as a replacement -for configure.sh in a Windows native environment. configure.bat is actually -just a thin layer that executes configure.exe if it is available. If -configure.exe is not available, then configure.bat will attempt to build it -first. - -In order to build configure.exe from configure.c in the Windows native -environment, two assumptions are made: - -1) You have installed the MinGW GCC toolchain. This toolchain can be - downloaded from http://www.mingw.org/. It is recommended that you not - install the optional MSYS components as there may be conflicts. -2) That path to the bin/ directory containing mingw-gcc.exe must be - included in the PATH variable. - -convert-comments.c ------------------- - -Convert C++-style comments to C89 C-style comments. Usage:: - - convert-comments - -detab.c -------- - -Convert tabs to spaces in a file. Usage:: - - detab [-4] - -Default tab size is 8 spaces; -4 selects 4 space tab size. - -discover.py ------------ - -Example script for discovering devices in the local network. -It is the counter part to apps/netutils/discover - -gencromfs.c ------------ - -This is a C program that is used to generate CROMFS file system images. -Usage is simple:: - - gencromfs - -Where: - -- is the path to the directory will be at the root of the - new CROMFS file system image. -- the name of the generated, output C file. This file must - be compiled in order to generate the binary CROMFS file system - image. - -initialconfig.c ---------------- - -This is a C file that can be used to create an initial configuration. -This permits creating a new configuration from scratch, without -relying on any existing board configuration in place. This utility -will create a barebones .config file sufficient only for -instantiating the symbolic links necessary to do a real configuration. - -kconfig2html.c --------------- - -This is a C file that can be used to build a utility for converting the -NuttX configuration in the Kconfig files to an HTML document. This -auto-generated documentation will, eventually, replace the manually -updated configuration documentation that is falling woefully behind:: - - $ tools/kconfig2html.exe -h - USAGE: tools/kconfig2html [-d] [-a ] {-o ] [] - tools/kconfig2html [-h] - -Where:: - - -a : Select relative path to the apps/ directory. This path is relative - to the . Default: ../apps - -o : Send output to . Default: Output goes to stdout - -d : Enable debug output - -h : Prints this message and exits - is the directory containing the root Kconfig file. - Default : . - -NOTE: In order to use this tool, some configuration must be in-place with -all necessary symbolic links. You can establish the configured symbolic -links with:: - - make context - -or more quickly with:: - - make .dirlinks - -Libraries.mk, FlatLibs.mk, ProtectedLibs.mk, and KernelLib.mk -------------------------------------------------------------- - -Libraries.mk has the build rules for all NuttX libraries. - -FlatLibs.mk, ProtectedLibs.mk, and KernelLib.mk: These control the -selection of libraries to be built, depending on the selected build mode. - -lowhex.c --------- - -Convert hexadecimal representation in a file from upper- to lower-case. -Usage:: - - lowhex - -Makefile.[unix|win] -------------------- - -Unix.mk is the Makefile used when building NuttX in Unix-like systems. -It is selected from the top-level Makefile. - -Win.mk is the Makefile used when building natively under Windows. -It is selected from the top-level Makefile. - -mkconfig.c, cfgdefine.c, and cfgdefine.h ----------------------------------------- - -These are C files that are used to build mkconfig program. The mkconfig -program is used during the initial NuttX build. - -When you configure NuttX, you will copy a configuration file called .config -in the top level NuttX directory (See :doc:`/components/boards` or -Documentation/NuttXPortingGuide.html). The first time you make NuttX, -the top-level makefile will build the mkconfig executable from mkconfig.c -(using Makefile.host). The top-level Makefile will then execute the mkconfig -program to convert the .config file in the top level directory into -include/nuttx/config.h. config.h is a another version of the NuttX -configuration that can be included by C files. - -mkconfigvars.sh ---------------- - -The HTML documentation expects to have a copy of the auto-generated -configuration variable documentation Documentation/NuttXConfigVariables.html. -The script mkconfigvars.sh is a simple script that can be used to -re-generated that file as needed. - -Help:: - - $ tools/mkconfigvars.sh -h - tools/mkconfigvars.sh is a tool for generation of configuration variable documentation - -USAGE: tools/mkconfigvars.sh [-d|h] [-v ] - -Where:: - - -v - The NuttX version number expressed as a major, minor and patch number separated - by a period - -d - Enable script debug - -h - show this help message and exit - -mkexport.sh and Export.mk -------------------------------- - -These implement part of the top-level Makefile's 'export' target. That -target will bundle up all of the NuttX libraries, header files, and the -startup object into an export-able, binary NuttX distribution. The -Export.mk is used only by the mkexport.sh script to parse out options -from the top-level Make.defs file. - -USAGE: tools/mkexport.sh [-d] [-z] [-u] -t [-x ] -l "lib1 [lib2 [lib3 ...]]" - -This script also depends on the environment variable MAKE which is set -in the top-level Makefile before starting mkexport.sh. If MAKE is not -defined, the script will set it to `which make`. - -mkfsdata.pl ------------ - -This perl script is used to build the "fake" file system and CGI support -as needed for the apps/netutils/webserver. It is currently used only -by the Makefile at apps/examples/uip. That example serves as an example -of how to configure the uIP webserver "fake" file system. - -NOTE: This perl script comes from uIP and was (probably) written -by Adam Dunkels. uIP has a license that is compatible with NuttX. - -mkversion.c, cfgdefine.c, and cfgdefine.h ------------------------------------------ - -This is C file that is used to build mkversion program. The mkversion -program is used during the initial NuttX build. - -When you build NuttX there should be a version file called .version in -the top level NuttX directory (See Documentation/NuttXPortingGuide.html). -The first time you make NuttX, the top-level makefile will build the -mkversion executable from mkversion.c (using Makefile.host). The top-level -Makefile will then execute the mkversion program to convert the -.version file in the top level directory into include/nuttx/version.h. -version.h provides version information that can be included by C files. - -mksyscall.c, cvsparser.c, and cvsparser.h ------------------------------------------ - -This is a C file that is used to build mksyscall program. The mksyscall -program is used during the initial NuttX build by the logic in the top- -level syscall/ directory. - -If you build NuttX as a separately compiled, monolithic kernel and separate -applications, then there is a syscall layer that is used to get from the -user application space to the NuttX kernel space. In the user application -"proxies" for each of the kernel functions are provided. The proxies have -the same function signature as the kernel function, but only execute a -system call. - -Within the kernel, there are "stubs" for each of the system calls. The -stubs receive the marshalled system call data, and perform the actually -kernel function call (in kernel-mode) on behalf of the proxy function. - -Information about the stubs and proxies is maintained in a comma separated -value (CSV) file in the syscall/ directory. The mksyscall program will -accept this CVS file as input and generate all of the required proxy or -stub files as output. See :doc:`/components/syscall` for additional information. - -mksymtab.c, cvsparser.c, and cvsparser.h ----------------------------------------- - -This is a C file that is used to build symbol tables from comma separated -value (CSV) files. This tool is not used during the NuttX build, but -can be used as needed to generate files. - -USAGE: ./mksymtab [-d] [ []] - -Where:: - - : The path to the input CSV file (required) - : The path to the output symbol table file (required) - : Optional name for the symbol table variable - Default: "g_symtab" - : Optional name for the symbol table variable - Default: "g_nsymbols" - -d : Enable debug output - -Example:: - - cd nuttx/tools - cat ../syscall/syscall.csv ../lib/libc.csv | sort >tmp.csv - ./mksymtab.exe tmp.csv tmp.c - -mkctags.sh ----------- - -A script for creating ctags from Ken Pettit. See http://en.wikipedia.org/wiki/Ctags -and http://ctags.sourceforge.net/ - -nxstyle.c ---------- - -I am embarrassed that this is here. This program is a complete hack -but, unfortunately, it has become so useful to me that I need to keep -it here. - -A little background: I have tinkered with pretty printers for some -time and have not been happy with the results. An alternative that -occurred to me would be just a standard checker that examines a C -file that gives warnings for violations of the coding standard. - -This turns out to be more difficult that you might think. A pretty -printer understands C syntax: They break the file up into its C -components then reassembles the output in the format. But parsing the -C loses the original file layout and so it not useful in this case. - -This program instead, uses a collection of heuristics (i.e., hacks and -bandaids) to examine the C file for obvious violations of the coding -standard. This program is completely ignorant of C syntax; it simply -performs crude pattern matching to check the file. - -Prints formatted messages that are classified as info, warn, error, -fatal. In a parsable format that can be used by editors and IDEs. - -Usage:: - - nxstyle [-m ] [-v ] [-r ] - nxstyle -h this help - nxstyle -v where level is - 0 - no output - 1 - PASS/FAIL - 2 - output each line (default) - -See also indent.sh and uncrustify.cfg - -pic32mx -------- - -This directory contains build tools used only for PIC32MX/Z platforms - -bdf-convert.c -------------- - -This C file is used to build the bdf-converter program. The bdf-converter -program can be used to convert fonts in Bitmap Distribution Format (BDF) -into fonts that can be used in the NX graphics system. - -Below are general instructions for creating and installing a new font -in the NX graphic system: - -1. Locate a font in BDF format, -2. Use the bdf-converter program to convert the BDF font to the NuttX - font format. This will result in a C header file containing - definitions. That header file should be installed at, for example, - libnx/nxfonts/nxfonts_myfont.h. - -Create a new NuttX configuration variable. For example, suppose -you define the following variable: CONFIG_NXFONT_MYFONT. Then -you would need to: - -3. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file. - -A font ID number has to be assigned for each new font. The font ID -is defined in the file include/nuttx/nx/nxfonts.h. Those definitions -have to be extended to support your new font. Look at how the font ID -enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for your -new font in a similar fashion: - -4. include/nuttx/nx/nxfonts.h. Add your new font as a possible system - default font:: - - #if defined(CONFIG_NXFONT_SANS23X27) - # define NXFONT_DEFAULT FONTID_SANS23X27 - #elif defined(CONFIG_NXFONT_MYFONT) - # define NXFONT_DEFAULT FONTID_MYFONT - #endif - -Then define the actual font ID. Make sure that the font ID value -is unique:: - - enum nx_fontid_e - { - FONTID_DEFAULT = 0 /* The default font */ - #ifdef CONFIG_NXFONT_SANS23X27 - , FONTID_SANS23X27 = 1 /* The 23x27 sans serif font */ - #endif - #ifdef CONFIG_NXFONT_MYFONT - , FONTID_MYFONT = 2 /* My shiny, new font */ - #endif - ... - -Now add the font to the NX build system. There are several files that -you have to modify to do this. Look how the build system uses the -font CONFIG_NXFONT_SANS23X27 for examples: - -5. nuttx/graphics/Makefile. This file needs logic to auto-generate - a C source file from the header file that you generated with the - the bdf-converter program. Notice NXFONTS_FONTID=2; this must be - set to the same font ID value that you defined in the - include/nuttx/nx/nxfonts.h file:: - - genfontsources: - ifeq ($(CONFIG_NXFONT_SANS23X27),y) - @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS) - endif - ifeq ($(CONFIG_NXFONT_MYFONT),y) - @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS) - endif - -6. nuttx/libnx/nxfonts/Make.defs. Set the make variable NXFSET_CSRCS. - NXFSET_CSRCS determines the name of the font C file to build when - NXFONTS_FONTID=2:: - - ifeq ($(CONFIG_NXFONT_SANS23X27),y) - NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c - endif - ifeq ($(CONFIG_NXFONT_MYFONT),y) - NXFSET_CSRCS += nxfonts_bitmaps_myfont.c - endif - -7. nuttx/libnx/nxfonts/Makefile.sources. This is the Makefile used - in step 5 that will actually generate the font C file. So, given - your NXFONTS_FONTID=2, it needs to determine a prefix to use for - auto-generated variable and function names and (again) the name of - the auto-generated file to create (this must be the same name that - was used in nuttx/libnx/nxfonts/Make.defs):: - - ifeq ($(NXFONTS_FONTID),1) - NXFONTS_PREFIX := g_sans23x27_ - GEN_CSRC = nxfonts_bitmaps_sans23x27.c - endif - ifeq ($(NXFONTS_FONTID),2) - NXFONTS_PREFIX := g_myfont_ - GEN_CSRC = nxfonts_bitmaps_myfont.c - endif - -8. graphics/libnx/nxfonts_bitmaps.c. This is the file that contains - the generic font structures. It is used as a "template" file by - nuttx/libnx/nxfonts/Makefile.sources to create your customized - font data set:: - - #if NXFONTS_FONTID == 1 - # include "nxfonts_sans23x27.h" - #elif NXFONTS_FONTID == 2 - # include "nxfonts_myfont.h" - #else - # error "No font ID specified" - #endif - - Where nxfonts_myfont.h is the NuttX font file that we generated in - step 2 using the bdf-converter tool. - -9. libnx/nxfonts/nxfonts_getfont.c. Finally, we need to extend the - logic that does the run-time font lookups so that can find our new - font. The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid). - The new font information needs to be added to data structures used by - that function:: - - #ifdef CONFIG_NXFONT_SANS23X27 - extern const struct nx_fontpackage_s g_sans23x27_package; - #endif - #ifdef CONFIG_NXFONT_MYFONT - extern const struct nx_fontpackage_s g_myfont_package; - #endif - - static FAR const struct nx_fontpackage_s *g_fontpackages[] = - { - #ifdef CONFIG_NXFONT_SANS23X27 - &g_sans23x27_package, - #endif - #ifdef CONFIG_NXFONT_MYFONT - &g_myfont_package, - #endif - NULL - }; - -define.sh and define.bat ------------------------- - -Different compilers have different conventions for specifying pre- -processor definitions on the compiler command line. This bash -script allows the build system to create command line definitions -without concern for the particular compiler in use. - -The define.bat script is a counterpart for use in the native Windows -build. - -flash_writer.py ---------------- - -This flash writer is using the xmodem for firmware transfer on -boards based on cxd56 chip (Ex. Spresense). This tool depends on -the xmodem package (https://pypi.org/project/xmodem/). - -for flashing the .spk image to the board please use: -tools/flash_writer.py -s -c /dev/ttyUSB0 -d -b 115200 -n nuttx.spk - -ide_exporter.py ---------------- - -This Python script will help to create NuttX project in the IAR and -uVision IDEs. These are few simple the steps to export the IDE -workspaces. - -1) Start the NuttX build from the Cygwin command line before trying to - create your project by running:: - - make V=1 |& tee build_log - - This is necessary to certain auto-generated files and directories that - will be needed. This will provide the build log to construct the IDE - project also. - -2) Export the IDE project base on that make log. The script usage: - - usage: ide_exporter.py [-h] [-v] [-o OUT_DIR] [-d] build_log {iar,uvision_armcc,uvision_gcc} template_dir - - positional arguments:: - - build_log Log file from make V=1 - {iar,uvision_armcc,uvision_gcc} - The target IDE: iar, uvision_gcc, (uvision_armcc is experimental) - template_dir Directory that contains IDEs template projects - - optional arguments:: - - -h, --help show this help message and exit - -v, --version show program's version number and exit - -o OUT_DIR, --output OUT_DIR - Output directory - -d, --dump Dump project structure tree - - Example:: - - cd nuttx - make V=1 |& tee build_log - - ./tools/ide_exporter.py makelog_f2nsh_c iar ./boards////ide/template/iar -o ./boards////ide/nsh/iar - - or:: - - ./tools/ide_exporter.py makelog_f2nsh_c uvision_gcc ./boards////ide/template/uvision_gcc/ -o ./boards////ide/nsh/uvision - -3) Limitations: - - - IAR supports C only. Iar C++ does not compatible with g++ so disable - C++ if you want to use IAR. - - uvision_armcc : nuttx asm (inline and .asm) can't be compiled with - armcc so do not use this option. - - uvision_gcc : uvision project that uses gcc. Need to specify path to - gnu toolchain. - In uVison menu, select:: - - Project/Manage/Project Items.../FolderExtension/Use GCC compiler/ PreFix, Folder - -4) Template projects' constrains: - - - mcu, core, link script shall be configured in template project - - Templates' name are fixed: - - - template_nuttx.eww : IAR nuttx workspace template - - template_nuttx_lib.ewp : IAR nuttx library project template - - template_nuttx_main.ewp : IAR nuttx main project template - - template_nuttx.uvmpw : uVision workspace - - template_nuttx_lib.uvproj : uVision library project - - template_nuttx_main.uvproj : uVision main project - - iar: - - - Library option shall be set to 'None' so that IAR could use nuttx - libc - - __ASSEMBLY__ symbol shall be defined in assembler - - - uVision_gcc: - - - There should be one fake .S file in projects that has been defined - __ASSEMBLY__ in assembler. - - In Option/CC tab : disable warning - - In Option/CC tab : select Compile thump code (or Misc control = - -mthumb) - - template_nuttx_lib.uvproj shall add 'Post build action' to copy .a - file to .\lib - - template_nuttx_main.uvproj Linker: - - - Select 'Do not use Standard System Startup Files' and 'Do not - use Standard System Libraries' - - Do not select 'Use Math libraries' - - Misc control = --entry=__start - -5) How to create template for other configurations: - - 1) uVision with gcc toolchain: - - - Copy 3 uVision project files - - Select the MCU for main and lib project - - Correct the path to ld script if needed - - 2) iar: - - - Check if the arch supports IAR (only armv7-m is support IAR - now) - - Select the MCU for main and lib project - - Add new ld script file for IAR - -NOTE: Due to bit rot, the template files for the stm3220g-eval and for -the stm32f429-disco have been removed from the NuttX repository. For -reference, they can be found in the Obsoleted repository at -Obsoleted/stm32f429i_disco/ltcd/template and at -Obsoleted/stm3220g-eval/template. - -incdir.sh, incdir.bat, and incdir.c ------------------------------------ - -Different compilers have different conventions for specifying lists -of include file paths on the compiler command line. This incdir.sh -bash script allows the build system to create include file paths without -concern for the particular compiler in use. - -The incdir.bat script is a counterpart for use in the native Windows -build. However, there is currently only one compiler supported in -that context: MinGW-GCC. - -incdir.c is a higher performance version of incdir.sh, converted to C. - -indent.sh ---------- - -This script can be used to indent .c and .h files in a manner similar -to the NuttX coding style. It doesn't do a really good job, however -(see below and the comments at the top of the indent.sh file). - -USAGE:: - - tools/indent.sh [-d] [-p] -o - tools/indent.sh [-d] [-p] - tools/indent.sh [-d] -h - -Where:: - - - - A single, unformatted input file - - - A list of unformatted input files that will be reformatted in place. - -o - Write the single, reformatted to . - will not be modified. - -d - Enable script debug - -p - Comments are pre-formatted. Do not reformat. - -h - Show this help message and exit - -The conversions make by the indent.sh script differs from the NuttX coding -style in that: - -1. The coding standard requires that the trailing ``*/`` of a multi-line - comment be on a separate line. By default, indent.sh will put the - final ``*/`` on the same line as the last comment text. If your C file - already has properly formatted comments then using the ``-p`` option will - eliminate that bad behavior - -2. If your source file has highly formatted comments containing things - such as tables or lists, then use the -p option to preserve those - pre-formatted comments. - -3. I usually align things vertically (like '=' in assignments), - -4. indent.sh puts a bogus blank line at the top of the file, - -5. I don't like the way it handles nested conditional compilation - intermixed with code. I prefer the preprocessor conditional tests - be all right justified in that case. - -6. I also indent brackets differently on structures than does this script. - -7. I normally use no spaces in casts. indent.sh adds spaces in casts like - ``(FAR void *)&foo`` becomes ``(FAR void *) & foo``. - -8. When used with header files, the initial idempotence conditional test - causes all preprocessor directives to be indented in the file. So for - header files, you will need to substitute "^# " with "#" in the - converted header file. - -You will manually need to check for the issues listed above after -performing the conversions. nxstyle.c provides a good test that will -catch most of the indent.sh screw-ups. Together, they do a pretty good -job of formatting. - -See also nxstyle.c and uncrustify.cfg - -kconfig.bat ------------ - -Recent versions of NuttX support building NuttX from a native Windows -CMD.exe shell. But kconfig-frontends is a Linux tool and is not yet -available in the pure CMD.exe environment. At this point, there are -only a few options for the Windows user (see the top-level README.txt -file). - -You can, with some effort, run the Cygwin kconfig-mconf tool directly -in the CMD.exe shell. In this case, you do not have to modify the -.config file, but there are other complexities: You need to -temporarily set the Cygwin directories in the PATH variable and -then run kconfig-mconf outside of the Make system. - -kconfig.bat is a Windows batch file at tools/kconfig.bat that automates -these steps. It is used from the top-level NuttX directory like:: - - tools/kconfig menuconfig - -NOTE: There is currently an issue with accessing DOS environment -variables from the Cygwin kconfig-mconf running in the CMD.exe shell. -The following change to the top-level Kconfig file seems to work around -these problems:: - - config APPSDIR - string - - option env="APPSDIR" - + default "../apps" - -.. _build_system_linking: - -link.sh, link.bat, copydir.sh, copydir.bat, unlink.sh, and unlink.bat ---------------------------------------------------------------------- - -Different file systems have different capabilities for symbolic links. -Some Windows file systems have no native support for symbolic links. -Cygwin running under Windows has special links built in that work with -all cygwin tools. However, they do not work when Windows native tools -are used with cygwin. In that case something different must be done. - -If you are building under Linux or under cygwin with a cygwin tool -chain, then your Make.defs file may have definitions like the -following:: - - DIRLINK = $(TOPDIR)/tools/link.sh - DIRUNLINK = (TOPDIR)/tools/unlink.sh - -The first definition is not always present because link.sh is the -default. link.sh is a bash script that performs a normal, Linux-style -symbolic link; unlink.sh is a do-it-all unlinking script. - -But if you are building under cygwin using a Windows native toolchain -within a POSIX framework (such as Cygwin), then you will need something -like the following in you Make.defs file:: - - DIRLINK = $(TOPDIR)/tools/copydir.sh - DIRUNLINK = (TOPDIR)/tools/unlink.sh - -copydir.sh will copy the whole directory instead of linking it. - -Finally, if you are running in a pure native Windows environment with -a CMD.exe shell, then you will need something like this:: - - DIRLINK = $(TOPDIR)/tools/copydir.bat - DIRUNLINK = (TOPDIR)/tools/unlink.bat - -Note that this will copy directories. link.bat might also be used in -this case. link.bat will attempt to create a symbolic link using the -NTFS mklink.exe command instead of copying files. That logic, however, -has not been verified as of this writing. - -.. _makefile_host: - -Makefile.host -------------- - -This is the makefile that is used to make the mkconfig program from -the mkconfig.c C file, the cmpconfig program from cmpconfig.c C file, -the mkversion program from the mkconfig.c C file, or the mksyscall -program from the mksyscall.c file. Usage:: - - cd tools/ - make -f Makefile.host - -mkromfsimg.sh -------------- - -This script may be used to automate the generation of a ROMFS file system -image. It accepts an rcS script "template" and generates an image that -may be mounted under /etc in the NuttX pseudo file system. - -TIP: Edit the resulting header file and mark the generated data values -as 'const' so that they will be stored in FLASH. - -.. _mkdeps: - -mkdeps.c, cnvwindeps.c, mkwindeps.sh, and mknulldeps.sh -------------------------------------------------------- - -NuttX uses the GCC compiler's capabilities to create Makefile dependencies. -The program mkdeps is used to run GCC in order to create the dependencies. -If a NuttX configuration uses the GCC toolchain, its Make.defs file (see -:doc:`/components/boards`) will include a line like:: - - MKDEP = $(TOPDIR)/tools/mkdeps[.exe] (See NOTE below) - -If the NuttX configuration does not use a GCC compatible toolchain, then -it cannot use the dependencies and instead it uses mknulldeps.sh:: - - MKDEP = $(TOPDIR)/tools/mknulldeps.sh - -The mknulldeps.sh is a stub script that does essentially nothing. - -mkwindeps.sh is a version that creates dependencies using the Windows -native toolchain. That generates Windows native paths in the dependency -file. But the mkwindeps.sh uses cnvwindeps.c to convert the Windows -paths to POSIX paths. This adds some time to the Windows dependency -generation but is generally the best option available for that mixed -environment of Cygwin with a native Windows GCC toolchain. - -mkdeps.c generates mkdeps (on Linux) or mkdeps.exe (on Windows). -However, this version is still under-development. It works well in -the all POSIX environment or in the all Windows environment but also -does not work well in mixed POSIX environment with a Windows toolchain. -In that case, there are still issues with the conversion of things like -'c:\Program Files' to 'c:program files' by bash. Those issues may, -eventually be solvable but for now continue to use mkwindeps.sh in -that mixed environment. - -netusb.sh ---------- - -Helper script used to set up the CDC ECM Ethernet Over USB driver, -host routes, and IP Tables rules to support networking with a NuttX -system that has a CDC ECM Ethernet Over USB driver configured. Only -supported on Linux. - -General usage: - - $ ./tools/netusb.sh - Usage: tools/netusb.sh - -This has been tested on the SAMA5D3-Xplained board; see -`Documentation/platforms/arm/sama5/boards/sama5d3-xplained/README.txt` -for more information on how to configure the CDC ECM driver for that board. - -nxtagspkgsfetch.sh ------------------- - -This script downloads all NuttX RTOS and Application snapshot packages -from the upstream git repository based on the provided git tags list. -These are NOT official release packages as checksum will differ. -When launched from the local NuttX git repository clone the script will -obtain all available tags to be downloaded, otherwise list of tags needs -to be provided manually (or when just selected tag is required). -This script uses ``wget`` underneath, make sure this tool is installed. -Fetch log file is created with a timestamp in name next to the packages. - -Having all tags packaged is important for changes comparison -between specific versions, testing a specific version, compatibility -checks, searching for a feature introduction timeline, etc. - -Usage: ``./nxtagspkgsfetch.sh [download_path] [tags_list_space_separated]`` - -You can provide optional download path (default ``../../nuttx-packages``) -and tags list to get packages for (default all tags from local git clone). -When providing tags you also need to provide download path. - -refresh.sh ----------- - -[NOTE: This script with --silent is really obsolete. refresh with the -silent option really adds default values. However, as of 217-07-09, -defconfig files are retained in a compressed format, i.e., with default -values removed. So the --silent option will accomplish nothing. -Without --silent, you will have the opportunity over override the default -value from the command line and, in that case, the script may still have -some minimal value.] - -This is a bash script that automatics refreshing of board default -configuration (defconfig) files. It does not do anything special -that you cannot do manually, but is useful for me when I have to -update dozens of configuration files. - -Configuration files have to be updated because over time, the -configuration settings change: New configurations are added and -new dependencies are added. So an old configuration file may -not be usable anymore until it is refreshed. - -Help is also available:: - - $ tools/refresh.sh --help - tools/refresh.sh is a tool for refreshing board configurations - -USAGE: ``./refresh.sh [options] ||:+`` - -Where [options] include:: - - --debug - Enable script debug - --silent - Update board configuration without interaction - --defaults - Do not prompt for new default selections; accept all recommended default values - --help - Show this help message and exit - - The board directory under nuttx/boards - - The board configuration directory under nuttx/boards/// - -The steps to refresh the file taken by refresh.sh are: - -1. Make tools/cmpconfig if it is not already built. - -2. Copy the defconfig file to the top-level NuttX - directory as .config (being careful to save any previous - .config file that you might want to keep!). - -3. Execute 'make oldconfig' to update the configuration. - 'make oldconfig' will prompt you for each change in the - configuration that requires that you make some decision. - With the --silent option, the script will use 'make - oldefconfig' instead and you won't have to answer any - questions; the refresh will simply accept the default - value for any new configuration settings. - -4. Then it runs tools/cmpconfig to show the real differences - between the configuration files. Configuration files are - complex and things can move around so a simple 'diff' between - two configuration files is often not useful. But tools/cmpconfig - will show only the meaningful differences between the two - configuration files. - -5. It will edit the .config file to comment out the setting - of the CONFIG_APPS_DIR= setting. This setting should not - be in checked-in defconfig files because the actually must - be determined at the next time that the configuration is - installed. - -6. Finally, the refreshed defconfig file is copied back in - place where it can be committed with the next set of - difference to the command line. If you select the --silent - option, this file copy will occur automatically. Otherwise, - refresh.sh will prompt you first to avoid overwriting the - defconfig file with changes that you may not want. - -Usage examples: - -Update all boards without verbose output:: - - $ ./tools/refresh.sh --silent --defaults all - -Update all boards and configs from `arm` architecture:: - - $ ./tools/refresh.sh --silent arch:arm - -Update all boards from `stm32f7` chip family:: - - $ ./tools/refresh.sh --silent chip:stm32f7 - -Update all configs from `stm32f103-minimum` board:: - - $ ./tools/refresh.sh --silent board:stm32f103-minimum - -Update only the `nsh` config from stm32f103-minimum board:: - - $ ./tools/refresh.sh --silent stm32f103-minimum:nsh - -rmcr.c ------- - -Removes all white space from the end of lines. Whitespace here -includes space characters, TAB characters, horizontal and vertical -TABs, and carriage returns. Lines will be terminated with the -newline character only. - -sethost.sh ----------- - -Saved configurations may run on Linux, Cygwin (32- or 64-bit), or other -platforms. The platform characteristics can be changed use 'make -menuconfig'. Sometimes this can be confusing due to the differences -between the platforms. Enter sethost.sh - -sethost.sh is a simple script that changes a configuration to your -host platform. This can greatly simplify life if you use many different -configurations. For example, if you are running on Linux and you -configure like this:: - - $ tools/configure.sh board:configuration - -The you can use the following command to both (1) make sure that the -configuration is up to date, AND (2) the configuration is set up -correctly for Linux:: - - $ tools/sethost.sh -l - -Or, if you are on a Windows/Cygwin 64-bit platform:: - - $ tools/sethost.sh -c - -Other options are available:: - - $ ./sethost.sh -h - - USAGE: ./sethost.sh [-l|m|c|g|n] [make-opts] - ./sethost.sh -h - - Where: - -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), - MSYS/MSYS2 (g) or Windows native (n). Default Linux - make-opts directly pass to make - -h will show this help test and terminate - -simhostroute.sh ---------------- - -Helper script used to set up the tap driver, host routes, -and IP Tables rules to support networking with the -simulator under Linux. General usage:: - - $ tools/simhostroute.sh - Usage: tools/simhostroute.sh - -See boards/sim/sim/sim/NETWORK-LINUX.txt for further information - -simbridge.sh ------------- - -Helper script used to set up a bridge to support networking with the -simulator under Linux. General usage:: - - $ tools/simbridge.sh - Usage: tools/simbridge.sh - -See boards/sim/sim/sim/NETWORK-LINUX.txt for further information - -showsize.sh ------------ - -Show the top 10 biggest memory hogs in code and data spaces. This -must be executed from the top-level NuttX directory like:: - - $ tools/showsize.sh - TOP 10 BIG DATA - ... - TOP 10 BIG CODE - ... - -testbuild.sh ------------- - -This script automates building of a set of configurations. The intent is -simply to assure that the set of configurations build correctly. The -h -option shows the usage:: - - $ ./testbuild.sh -h - - USAGE: ./testbuild.sh [-l|m|c|g|n] [-d] [-e ] [-x] [-j ] [-a ] [-t ] [-p] [-G] - ./testbuild.sh -h - - Where: - -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), - MSYS/MSYS2 (g) or Windows native (n). Default Linux - -d enables script debug output - -e pass extra c/c++ flags such as -Wno-cpp via make command line - -x exit on build failures - -j passed on to make. Default: No -j make option. - -a provides the relative path to the apps/ directory. Default ../apps - -t provides the absolute path to top nuttx/ directory. Default ../nuttx - -p only print the list of configs without running any builds - -A store the build executable artifact in ARTIFACTDIR (defaults to ../buildartifacts - -C Skip tree cleanness check. - -G Use "git clean -xfdq" instead of "make distclean" to clean the tree. - This option may speed up the builds. However, note that: - * This assumes that your trees are git based. - * This assumes that only nuttx and apps repos need to be cleaned. - * If the tree has files not managed by git, they will be removed - as well. - -R execute "run" script in the config directories if exists. - -h will show this help test and terminate - selects the list of configurations to test. No default - - Your PATH variable must include the path to both the build tools and the - kconfig-frontends tools - -These script needs two pieces of information. - -a. A description of the platform that you are testing on. This description - is provided by the optional -l, -m, -c, -g and -n options. -b. A list of configurations to build. That list is provided by a test - list file. The final, non-optional parameter, , - provides the path to that file. - -The test list file is a sequence of build descriptions, one per line. One -build descriptions consists of two comma separated values. For example:: - - stm32f429i-disco:nsh - arduino-due:nsh - /arm - /risc-v - -The first value is the usual configuration description of the form -``:`` or ``/`` and must correspond to a -configuration or folder in the nuttx/boards directory. - -The second value is valid name for a toolchain configuration to use -when building the configuration. The set of valid toolchain -configuration names depends on the underlying architecture of the -configured board. - -The prefix ``-`` can be used to skip a configuration:: - - -stm32f429i-disco/nsh - -or skip a configuration on a specific host(e.g. Darwin):: - - -Darwin,sim:rpserver - -uncrustify.cfg --------------- - -This is a configuration script for the uncrustify code beautifier. -Uncrustify does well with forcing braces into "if" statements and -indenting per the NuttX C coding standard. It correctly does things -like placing all braces on separate lines at the proper indentation -level. It cannot handle certain requirements of the coding standard -such as - -- FAR attributes in pointer declarations. -- The NuttX standard function header block comments. -- Naming violations such as use of CamelCase variable names, - lower case pre-processor definitions, etc. - -Comment blocks, function headers, files headers, etc. must be formatted -manually. - -Its handling of block comments is fragile. If the comment is perfect, -it leaves it alone, but if the block comment is deemed to need a fix -it starts erroneously indenting the continuation lines of the comment. - -- uncrustify.cfg messed up the indent of most block comments. - cmt_sp_before_star_cont is applied inconsistently. I added:: - - cmt_indent_multi = false # disable all multi-line comment changes - - to the .cfg file to limit its damage to block comments. -- It is very strict at wrapping lines at column 78. Even when column 79 - just contained the ``/`` of a closing ``*/``. That created many - bad continuation lines. - -- It moved '{' that opened a struct to the line defining the struct. - nl_struct_brace = add (or force) seemed to be ignored. - -- It also aligned variable names in declarations and '=' signs in - assignment statements in a seemingly arbitrary manner. Making changes - that were not necessary. - -NOTE: uncrustify.cfg should **ONLY** be used with new files that have an -inconsistent coding style. uncrustify.cfg should get you in the ballpark, -but you should expect to review and hand-edit the files to assume 100% -compliance. - -WARNING: **NEVER** use uncrustify.cfg for modifications to existing NuttX -files. It will probably corrupt the style in subtle ways! - -This was last verified against uncrustify 0.66.1 by Bob Feretich. - -About uncrustify: Uncrustify is a highly configurable, easily modifiable -source code beautifier. To learn more about uncrustify: - - http://uncrustify.sourceforge.net/ - -Source code is available on GitHub: - - https://github.com/uncrustify/uncrustify - -Binary packages are available for Linux via command line installers. -Binaries for both Windows and Linux are available at: - - https://sourceforge.net/projects/uncrustify/files/ - -See also indent.sh and nxstyle.c - -parsetrace.py -------------- - .. toctree:: - :maxdepth: 2 - :hidden: + :caption: Tool documentation pages + :maxdepth: 1 + :glob: - parsetrace - -``parsetrace.py`` is a Python script for parsing and converting NuttX trace -logs. See dedicated :doc:`parsetrace` section for details. - -zds ---- - -This directory contains build tools used only with the ZDS-II -platforms (z8, ez80, zNeo). - -zipme.sh --------- - -I use this script to create the nuttx-xx.yy.tar.gz tarballs for -release. It is handy because it also does the kind of clean up -that you need to do to make a clean code release. -It can also PGP sign the final tarballs and create their SHA512 hash. -Any VCS files or directories are excluded from the final tarballs. - - -Help:: - - $ ./tools/zipme.sh -h - USAGE="USAGE: ./tools/zipme.sh [-d|h|v|s] [-b [-e ] [-k ] []" - -Examples:: - - ./tools/zipme.sh -s 9.0.0 - Create version 9.0.0 tarballs and sign them. - ./tools/zipme.sh -s -k XXXXXX 9.0.0 - Same as above but use the key-id XXXXXX to sign the tarballs - ./tools/zipme.sh -e "*.swp tmp" 9.0.0 - Create the tarballs but exclude any .swp file and the "tmp" directory. + ./* diff --git a/Documentation/components/tools/initialconfig.rst b/Documentation/components/tools/initialconfig.rst new file mode 100644 index 00000000000..0e9afb3d214 --- /dev/null +++ b/Documentation/components/tools/initialconfig.rst @@ -0,0 +1,9 @@ +=================== +``initialconfig.c`` +=================== + +This is a C file that can be used to create an initial configuration. This +permits creating a new configuration from scratch, without relying on any +existing board configuration in place. This utility will create a barebones +``.config`` file sufficient only for instantiating the symbolic links necessary +to do a real configuration. diff --git a/Documentation/components/tools/kconfig-bat.rst b/Documentation/components/tools/kconfig-bat.rst new file mode 100644 index 00000000000..0d81a85a378 --- /dev/null +++ b/Documentation/components/tools/kconfig-bat.rst @@ -0,0 +1,30 @@ +=============== +``kconfig.bat`` +=============== + +Recent versions of NuttX support building NuttX from a native Windows +CMD.exe shell. But kconfig-frontends is a Linux tool and is not yet +available in the pure CMD.exe environment. At this point, there are +only a few options for the Windows user (see the top-level README.txt +file). + +You can, with some effort, run the Cygwin kconfig-mconf tool directly +in the CMD.exe shell. In this case, you do not have to modify the +.config file, but there are other complexities: You need to +temporarily set the Cygwin directories in the PATH variable and +then run kconfig-mconf outside of the Make system. + +kconfig.bat is a Windows batch file at tools/kconfig.bat that automates +these steps. It is used from the top-level NuttX directory like:: + + tools/kconfig menuconfig + +NOTE: There is currently an issue with accessing DOS environment +variables from the Cygwin kconfig-mconf running in the CMD.exe shell. +The following change to the top-level Kconfig file seems to work around +these problems:: + + config APPSDIR + string + - option env="APPSDIR" + + default "../apps" diff --git a/Documentation/components/tools/kconfig2html.rst b/Documentation/components/tools/kconfig2html.rst new file mode 100644 index 00000000000..68c15c7d861 --- /dev/null +++ b/Documentation/components/tools/kconfig2html.rst @@ -0,0 +1,37 @@ +================== +``kconfig2html.c`` +================== + +This is a C file that can be used to build a utility for converting the +NuttX configuration in the Kconfig files to an HTML document. This +auto-generated documentation will, eventually, replace the manually +updated configuration documentation that is falling woefully behind: + +.. code:: console + + $ tools/kconfig2html.exe -h + USAGE: tools/kconfig2html [-d] [-a ] {-o ] [] + tools/kconfig2html [-h] + +Where:: + + -a : Select relative path to the apps/ directory. This path is relative + to the . Default: ../apps + -o : Send output to . Default: Output goes to stdout + -d : Enable debug output + -h : Prints this message and exits + is the directory containing the root Kconfig file. + Default : . + + +.. note:: + + In order to use this tool, some configuration must be in-place with + all necessary symbolic links. You can establish the configured symbolic + links with:: + + make context + + or more quickly with:: + + make .dirlinks diff --git a/Documentation/components/tools/libraries-libs.rst b/Documentation/components/tools/libraries-libs.rst new file mode 100644 index 00000000000..6d0315fef55 --- /dev/null +++ b/Documentation/components/tools/libraries-libs.rst @@ -0,0 +1,8 @@ +========================================================================= +``Libraries.mk``, ``FlatLibs.mk``, ``ProtectedLibs.mk``, ``KernelLib.mk`` +========================================================================= + +Libraries.mk has the build rules for all NuttX libraries. + +FlatLibs.mk, ProtectedLibs.mk, and KernelLib.mk: These control the +selection of libraries to be built, depending on the selected build mode. diff --git a/Documentation/components/tools/link-copydir-unlink.rst b/Documentation/components/tools/link-copydir-unlink.rst new file mode 100644 index 00000000000..5012bbfb463 --- /dev/null +++ b/Documentation/components/tools/link-copydir-unlink.rst @@ -0,0 +1,42 @@ +.. _build_system_linking: + +============================================================ +``link.[sh|bat]``, ``copydir.[sh|bat]``, ``unlink.[sh|bat]`` +============================================================ + +Different file systems have different capabilities for symbolic links. +Some Windows file systems have no native support for symbolic links. +Cygwin running under Windows has special links built in that work with +all cygwin tools. However, they do not work when Windows native tools +are used with cygwin. In that case something different must be done. + +If you are building under Linux or under cygwin with a cygwin tool +chain, then your Make.defs file may have definitions like the +following:: + + DIRLINK = $(TOPDIR)/tools/link.sh + DIRUNLINK = (TOPDIR)/tools/unlink.sh + +The first definition is not always present because link.sh is the +default. link.sh is a bash script that performs a normal, Linux-style +symbolic link; unlink.sh is a do-it-all unlinking script. + +But if you are building under cygwin using a Windows native toolchain +within a POSIX framework (such as Cygwin), then you will need something +like the following in you Make.defs file:: + + DIRLINK = $(TOPDIR)/tools/copydir.sh + DIRUNLINK = (TOPDIR)/tools/unlink.sh + +copydir.sh will copy the whole directory instead of linking it. + +Finally, if you are running in a pure native Windows environment with +a CMD.exe shell, then you will need something like this:: + + DIRLINK = $(TOPDIR)/tools/copydir.bat + DIRUNLINK = (TOPDIR)/tools/unlink.bat + +Note that this will copy directories. link.bat might also be used in +this case. link.bat will attempt to create a symbolic link using the +NTFS mklink.exe command instead of copying files. That logic, however, +has not been verified as of this writing. diff --git a/Documentation/components/tools/lowhex.rst b/Documentation/components/tools/lowhex.rst new file mode 100644 index 00000000000..4c3278c3f05 --- /dev/null +++ b/Documentation/components/tools/lowhex.rst @@ -0,0 +1,11 @@ +============ +``lowhex.c`` +============ + +Convert hexadecimal representation in a file from upper-case to lower-case. + +Usage: + +.. code:: console + + $ lowhex diff --git a/Documentation/components/tools/makefile-host.rst b/Documentation/components/tools/makefile-host.rst new file mode 100644 index 00000000000..d15ce693382 --- /dev/null +++ b/Documentation/components/tools/makefile-host.rst @@ -0,0 +1,17 @@ +.. _makefile_host: + +================= +``Makefile.host`` +================= + +This is the makefile that is used to make the mkconfig program from +the mkconfig.c C file, the cmpconfig program from cmpconfig.c C file, +the mkversion program from the mkconfig.c C file, or the mksyscall +program from the mksyscall.c file. + +Usage: + +.. code:: console + + $ cd tools/ + $ make -f Makefile.host diff --git a/Documentation/components/tools/makefile-unix-win.rst b/Documentation/components/tools/makefile-unix-win.rst new file mode 100644 index 00000000000..494c938e295 --- /dev/null +++ b/Documentation/components/tools/makefile-unix-win.rst @@ -0,0 +1,10 @@ +======================= +``Makefile.[unix|win]`` +======================= + +Unix.mk is the Makefile used when building NuttX in Unix-like systems. +It is selected from the top-level Makefile. + +Win.mk is the Makefile used when building natively under Windows. +It is selected from the top-level Makefile. + diff --git a/Documentation/components/tools/mkconfig-cfg.rst b/Documentation/components/tools/mkconfig-cfg.rst new file mode 100644 index 00000000000..78b365388dc --- /dev/null +++ b/Documentation/components/tools/mkconfig-cfg.rst @@ -0,0 +1,15 @@ +================================================ +``mkconfig.c``, ``cfgdefine.c``, ``cfgdefine.h`` +================================================ + +These are C files that are used to build mkconfig program. The mkconfig +program is used during the initial NuttX build. + +When you configure NuttX, you will copy a configuration file called .config +in the top level NuttX directory (See :doc:`/components/boards` or +Documentation/NuttXPortingGuide.html). The first time you make NuttX, +the top-level makefile will build the mkconfig executable from mkconfig.c +(using Makefile.host). The top-level Makefile will then execute the mkconfig +program to convert the .config file in the top level directory into +include/nuttx/config.h. config.h is a another version of the NuttX +configuration that can be included by C files. diff --git a/Documentation/components/tools/mkconfigvars.rst b/Documentation/components/tools/mkconfigvars.rst new file mode 100644 index 00000000000..2ada6928446 --- /dev/null +++ b/Documentation/components/tools/mkconfigvars.rst @@ -0,0 +1,27 @@ +=================== +``mkconfigvars.sh`` +=================== + +The HTML documentation expects to have a copy of the auto-generated +configuration variable documentation Documentation/NuttXConfigVariables.html. +The script mkconfigvars.sh is a simple script that can be used to +re-generated that file as needed. + +Help: + +.. code:: console + + $ tools/mkconfigvars.sh -h + tools/mkconfigvars.sh is a tool for generation of configuration variable documentation + + USAGE: tools/mkconfigvars.sh [-d|h] [-v ] + +Where:: + + -v + The NuttX version number expressed as a major, minor and patch number separated + by a period + -d + Enable script debug + -h + show this help message and exit diff --git a/Documentation/components/tools/mkctags.rst b/Documentation/components/tools/mkctags.rst new file mode 100644 index 00000000000..c6139206823 --- /dev/null +++ b/Documentation/components/tools/mkctags.rst @@ -0,0 +1,6 @@ +============== +``mkctags.sh`` +============== + +A script for creating ctags from Ken Pettit. See http://en.wikipedia.org/wiki/Ctags +and http://ctags.sourceforge.net/ diff --git a/Documentation/components/tools/mkdeps.rst b/Documentation/components/tools/mkdeps.rst new file mode 100644 index 00000000000..d5670669328 --- /dev/null +++ b/Documentation/components/tools/mkdeps.rst @@ -0,0 +1,35 @@ +.. _mkdeps: + +=================================================================== +``mkdeps.c``, ``cnvwindeps.c``, ``mkwindeps.sh``, ``mknulldeps.sh`` +=================================================================== + +NuttX uses the GCC compiler's capabilities to create Makefile dependencies. +The program mkdeps is used to run GCC in order to create the dependencies. +If a NuttX configuration uses the GCC toolchain, its Make.defs file (see +:doc:`/components/boards`) will include a line like:: + + MKDEP = $(TOPDIR)/tools/mkdeps[.exe] (See NOTE below) + +If the NuttX configuration does not use a GCC compatible toolchain, then +it cannot use the dependencies and instead it uses mknulldeps.sh:: + + MKDEP = $(TOPDIR)/tools/mknulldeps.sh + +The mknulldeps.sh is a stub script that does essentially nothing. + +mkwindeps.sh is a version that creates dependencies using the Windows +native toolchain. That generates Windows native paths in the dependency +file. But the mkwindeps.sh uses cnvwindeps.c to convert the Windows +paths to POSIX paths. This adds some time to the Windows dependency +generation but is generally the best option available for that mixed +environment of Cygwin with a native Windows GCC toolchain. + +mkdeps.c generates mkdeps (on Linux) or mkdeps.exe (on Windows). +However, this version is still under-development. It works well in +the all POSIX environment or in the all Windows environment but also +does not work well in mixed POSIX environment with a Windows toolchain. +In that case, there are still issues with the conversion of things like +'c:\Program Files' to 'c:program files' by bash. Those issues may, +eventually be solvable but for now continue to use mkwindeps.sh in +that mixed environment. diff --git a/Documentation/components/tools/mkexport.rst b/Documentation/components/tools/mkexport.rst new file mode 100644 index 00000000000..41fe277b845 --- /dev/null +++ b/Documentation/components/tools/mkexport.rst @@ -0,0 +1,15 @@ +============================== +``mkexport.sh``, ``Export.mk`` +============================== + +These implement part of the top-level Makefile's 'export' target. That +target will bundle up all of the NuttX libraries, header files, and the +startup object into an export-able, binary NuttX distribution. The +Export.mk is used only by the mkexport.sh script to parse out options +from the top-level Make.defs file. + +USAGE: tools/mkexport.sh [-d] [-z] [-u] -t [-x ] -l "lib1 [lib2 [lib3 ...]]" + +This script also depends on the environment variable MAKE which is set +in the top-level Makefile before starting mkexport.sh. If MAKE is not +defined, the script will set it to `which make`. diff --git a/Documentation/components/tools/mkfsdata-pl.rst b/Documentation/components/tools/mkfsdata-pl.rst new file mode 100644 index 00000000000..99001628a51 --- /dev/null +++ b/Documentation/components/tools/mkfsdata-pl.rst @@ -0,0 +1,13 @@ +=============== +``mkfsdata.pl`` +=============== + +This perl script is used to build the "fake" file system and CGI support +as needed for the apps/netutils/webserver. It is currently used only +by the Makefile at apps/examples/uip. That example serves as an example +of how to configure the uIP webserver "fake" file system. + +.. note:: + + This perl script comes from uIP and was (probably) written by Adam Dunkels. + uIP has a license that is compatible with NuttX. diff --git a/Documentation/components/tools/mkromfsimg.rst b/Documentation/components/tools/mkromfsimg.rst new file mode 100644 index 00000000000..1dbd4f2a101 --- /dev/null +++ b/Documentation/components/tools/mkromfsimg.rst @@ -0,0 +1,12 @@ +================= +``mkromfsimg.sh`` +================= + +This script may be used to automate the generation of a ROMFS file system +image. It accepts an rcS script "template" and generates an image that +may be mounted under /etc in the NuttX pseudo file system. + +.. tip:: + + Edit the resulting header file and mark the generated data values as + ``const`` so that they will be stored in FLASH. diff --git a/Documentation/components/tools/mksymtab-cvsparser.rst b/Documentation/components/tools/mksymtab-cvsparser.rst new file mode 100644 index 00000000000..5e42d274089 --- /dev/null +++ b/Documentation/components/tools/mksymtab-cvsparser.rst @@ -0,0 +1,31 @@ +================================================ +``mksymtab.c``, ``cvsparser.c``, ``cvsparser.h`` +================================================ + +This is a C file that is used to build symbol tables from comma separated +value (CSV) files. This tool is not used during the NuttX build, but +can be used as needed to generate files. + +Usage: + +.. code:: console + + $ ./mksymtab [-d] [ []] + +Where:: + + : The path to the input CSV file (required) + : The path to the output symbol table file (required) + : Optional name for the symbol table variable + Default: "g_symtab" + : Optional name for the symbol table variable + Default: "g_nsymbols" + -d : Enable debug output + +Example: + +.. code:: console + + $ cd nuttx/tools + $ cat ../syscall/syscall.csv ../lib/libc.csv | sort >tmp.csv + $ ./mksymtab.exe tmp.csv tmp.c diff --git a/Documentation/components/tools/mksyscall-cvsparser.rst b/Documentation/components/tools/mksyscall-cvsparser.rst new file mode 100644 index 00000000000..cd2070db952 --- /dev/null +++ b/Documentation/components/tools/mksyscall-cvsparser.rst @@ -0,0 +1,24 @@ +================================================= +``mksyscall.c``, ``cvsparser.c``, ``cvsparser.h`` +================================================= + +This is a C file that is used to build mksyscall program. The mksyscall +program is used during the initial NuttX build by the logic in the top- +level syscall/ directory. + +If you build NuttX as a separately compiled, monolithic kernel and separate +applications, then there is a syscall layer that is used to get from the +user application space to the NuttX kernel space. In the user application +"proxies" for each of the kernel functions are provided. The proxies have +the same function signature as the kernel function, but only execute a +system call. + +Within the kernel, there are "stubs" for each of the system calls. The +stubs receive the marshalled system call data, and perform the actually +kernel function call (in kernel-mode) on behalf of the proxy function. + +Information about the stubs and proxies is maintained in a comma separated +value (CSV) file in the syscall/ directory. The mksyscall program will +accept this CVS file as input and generate all of the required proxy or +stub files as output. See :doc:`/components/syscall` for additional information. + diff --git a/Documentation/components/tools/mkversion-cfgdefine.rst b/Documentation/components/tools/mkversion-cfgdefine.rst new file mode 100644 index 00000000000..0b3ed235573 --- /dev/null +++ b/Documentation/components/tools/mkversion-cfgdefine.rst @@ -0,0 +1,15 @@ +================================================= +``mkversion.c``, ``cfgdefine.c``, ``cfgdefine.h`` +================================================= + +This is C file that is used to build mkversion program. The mkversion +program is used during the initial NuttX build. + +When you build NuttX there should be a version file called .version in +the top level NuttX directory (See Documentation/NuttXPortingGuide.html). +The first time you make NuttX, the top-level makefile will build the +mkversion executable from mkversion.c (using Makefile.host). The top-level +Makefile will then execute the mkversion program to convert the +.version file in the top level directory into include/nuttx/version.h. +version.h provides version information that can be included by C files. + diff --git a/Documentation/components/tools/netusb.rst b/Documentation/components/tools/netusb.rst new file mode 100644 index 00000000000..4b0d7d867c8 --- /dev/null +++ b/Documentation/components/tools/netusb.rst @@ -0,0 +1,19 @@ +============= +``netusb.sh`` +============= + +Helper script used to set up the CDC ECM Ethernet Over USB driver, +host routes, and IP Tables rules to support networking with a NuttX +system that has a CDC ECM Ethernet Over USB driver configured. Only +supported on Linux. + +General usage: + +.. code:: console + + $ ./tools/netusb.sh + Usage: tools/netusb.sh + +This has been tested on the SAMA5D3-Xplained board; see +`Documentation/platforms/arm/sama5/boards/sama5d3-xplained/README.txt` +for more information on how to configure the CDC ECM driver for that board. diff --git a/Documentation/components/tools/nxstyle.rst b/Documentation/components/tools/nxstyle.rst new file mode 100644 index 00000000000..6eeedcad985 --- /dev/null +++ b/Documentation/components/tools/nxstyle.rst @@ -0,0 +1,35 @@ +============= +``nxstyle.c`` +============= + +I am embarrassed that this is here. This program is a complete hack but, +unfortunately, it has become so useful to me that I need to keep it here. + +A little background: I have tinkered with pretty printers for some +time and have not been happy with the results. An alternative that +occurred to me would be just a standard checker that examines a C +file that gives warnings for violations of the coding standard. + +This turns out to be more difficult that you might think. A pretty +printer understands C syntax: They break the file up into its C +components then reassembles the output in the format. But parsing the +C loses the original file layout and so it not useful in this case. + +This program instead, uses a collection of heuristics (i.e., hacks and +bandaids) to examine the C file for obvious violations of the coding +standard. This program is completely ignorant of C syntax; it simply +performs crude pattern matching to check the file. + +Prints formatted messages that are classified as info, warn, error, +fatal. In a parsable format that can be used by editors and IDEs. + +Usage:: + + nxstyle [-m ] [-v ] [-r ] + nxstyle -h this help + nxstyle -v where level is + 0 - no output + 1 - PASS/FAIL + 2 - output each line (default) + +See also indent.sh and uncrustify.cfg diff --git a/Documentation/components/tools/nxtagspkgsfetch.rst b/Documentation/components/tools/nxtagspkgsfetch.rst new file mode 100644 index 00000000000..a4c732ad094 --- /dev/null +++ b/Documentation/components/tools/nxtagspkgsfetch.rst @@ -0,0 +1,22 @@ +====================== +``nxtagspkgsfetch.sh`` +====================== + +This script downloads all NuttX RTOS and Application snapshot packages +from the upstream git repository based on the provided git tags list. +These are NOT official release packages as checksum will differ. +When launched from the local NuttX git repository clone the script will +obtain all available tags to be downloaded, otherwise list of tags needs +to be provided manually (or when just selected tag is required). +This script uses ``wget`` underneath, make sure this tool is installed. +Fetch log file is created with a timestamp in name next to the packages. + +Having all tags packaged is important for changes comparison +between specific versions, testing a specific version, compatibility +checks, searching for a feature introduction timeline, etc. + +Usage: ``./nxtagspkgsfetch.sh [download_path] [tags_list_space_separated]`` + +You can provide optional download path (default ``../../nuttx-packages``) +and tags list to get packages for (default all tags from local git clone). +When providing tags you also need to provide download path. diff --git a/Documentation/components/tools/parsetrace.rst b/Documentation/components/tools/parsetrace.rst index e8d71e18d6d..8ad0e60db36 100644 --- a/Documentation/components/tools/parsetrace.rst +++ b/Documentation/components/tools/parsetrace.rst @@ -1,5 +1,6 @@ -parsetrace.py -============= +================= +``parsetrace.py`` +================= `parsetrace.py` is a trace log parsing tool for the NuttX RTOS. It supports converting binary or text trace logs into a human-readable systrace format, and can resolve symbols and type information from ELF files. The tool also supports real-time trace data parsing via serial port. diff --git a/Documentation/components/tools/pic32mx.rst b/Documentation/components/tools/pic32mx.rst new file mode 100644 index 00000000000..76f09b9b498 --- /dev/null +++ b/Documentation/components/tools/pic32mx.rst @@ -0,0 +1,5 @@ +======= +pic32mx +======= + +This directory contains build tools used only for PIC32MX/Z platforms diff --git a/Documentation/components/tools/refresh.rst b/Documentation/components/tools/refresh.rst new file mode 100644 index 00000000000..52729971e33 --- /dev/null +++ b/Documentation/components/tools/refresh.rst @@ -0,0 +1,122 @@ +============== +``refresh.sh`` +============== + +.. note:: + + This script with ``--silent`` is really obsolete. The silent option really + adds default values. However, as of 217-07-09, defconfig files are retained + in a compressed format, i.e., with default values removed. So the + ``--silent`` option will accomplish nothing. Without ``--silent``, you will + have the opportunity over override the default value from the command line + and, in that case, the script may still have some minimal value. + +This is a bash script that automates refreshing of board default configuration +(defconfig) files. It does not do anything special that you cannot do manually, +but is useful for updating dozens of configuration files. It is also used in the +NuttX CI process. + +Configuration files have to be updated because over time, the configuration +settings change; new configurations are added and new dependencies are added. +So an old configuration file may not be usable anymore until it is refreshed. + +Help is also available: + +.. code:: console + + $ tools/refresh.sh --help + tools/refresh.sh is a tool for refreshing board configurations + + USAGE: tools/refresh.sh [options] :+ + + Where [options] include: + --debug + Enable script debug + --silent + Update board configuration without interaction. Implies --defaults. + Assumes no prompt for save. Use --silent --prompt to prompt before saving. + --prompt + Prompt before updating and overwriting the defconfig file. Default is to + prompt unless --silent + --defaults + Do not prompt for new default selections; accept all recommended default values + --nocopy + Do not copy defconfig from nuttx/boards//configs to nuttx/.config + --help + Show this help message and exit + + The board directory under nuttx/boards/arch/chip/ + + The board configuration directory under nuttx/boards/arch/chip//configs + + The architecture directory under nuttx/boards/ + + The chip family directory under nuttx/boards// + + Note1: all configurations are refreshed if : is replaced with "all" keyword + Note2: all configurations of arch XYZ are refreshed if "arch:" is passed + Note3: all configurations of chip XYZ are refreshed if "chip:" is passed + Note4: all configurations of board XYZ are refreshed if "board:" is passed + +The steps to refresh the file taken by ``refresh.sh`` are: + +1. Make ``tools/cmpconfig`` if it is not already built. + +2. Copy the defconfig file to the top-level NuttX directory as ``.config`` + (being careful to save any previous ``.config`` file that you might want to + keep!). + +3. Execute ``make` oldconfig` to update the configuration. ``make oldconfig`` + will prompt you for each change in the configuration that requires that you + make some decision. With the ``--silent`` option, the script will use ``make + oldefconfig`` instead and you won't have to answer any questions; the refresh + will simply accept the default value for any new configuration settings. + +4. Then it runs ``tools/cmpconfig`` to show the real differences between the + configuration files. Configuration files are complex and things can move + around so a simple 'diff' between two configuration files is often not + useful. But tools/cmpconfig will show only the meaningful differences + between the two configuration files. + +5. It will edit the .config file to comment out the setting of the + ``CONFIG_APPS_DIR=`` setting. This setting should not be in checked-in + defconfig files because the actually must be determined at the next time that + the configuration is installed. + +6. Finally, the refreshed defconfig file is copied back in place where it can be + committed with the next set of difference to the command line. If you select + the ``--silent`` option, this file copy will occur automatically. Otherwise, + refresh.sh will prompt you first to avoid overwriting the defconfig file with + changes that you may not want. + +Usage examples: + +Update all boards without verbose output: + +.. code:: console + + $ ./tools/refresh.sh --silent --defaults all + +Update all boards and configs from `arm` architecture: + +.. code:: console + + $ ./tools/refresh.sh --silent arch:arm + +Update all boards from ``stm32f7`` chip family: + +.. code:: console + + $ ./tools/refresh.sh --silent chip:stm32f7 + +Update all configs from ``stm32f103-minimum`` board: + +.. code:: console + + $ ./tools/refresh.sh --silent board:stm32f103-minimum + +Update only the `.nsh.` config from stm32f103-minimum board: + +.. code:: console + + $ ./tools/refresh.sh --silent stm32f103-minimum:nsh diff --git a/Documentation/components/tools/rmcr.rst b/Documentation/components/tools/rmcr.rst new file mode 100644 index 00000000000..f2e8ecd9bed --- /dev/null +++ b/Documentation/components/tools/rmcr.rst @@ -0,0 +1,7 @@ +========== +``rmcr.c`` +========== + +Removes all white space from the end of lines. Whitespace here includes space +characters, TAB characters, horizontal and vertical TABs, and carriage returns. +Lines will be terminated with the newline character only. diff --git a/Documentation/components/tools/sethost.rst b/Documentation/components/tools/sethost.rst new file mode 100644 index 00000000000..62fef45e16f --- /dev/null +++ b/Documentation/components/tools/sethost.rst @@ -0,0 +1,46 @@ +============== +``sethost.sh`` +============== + +Saved configurations may run on Linux, Cygwin (32- or 64-bit), or other +platforms. The platform characteristics can be changed use 'make menuconfig'. +Sometimes this can be confusing due to the differences between the platforms. +Enter sethost.sh + +sethost.sh is a simple script that changes a configuration to your host +platform. This can greatly simplify life if you use many different +configurations. For example, if you are running on Linux and you configure like +this: + +.. code:: console + + $ tools/configure.sh board:configuration + +The you can use the following command to both (1) make sure that the +configuration is up to date, AND (2) the configuration is set up +correctly for Linux: + +.. code:: console + + $ tools/sethost.sh -l + +Or, if you are on a Windows/Cygwin 64-bit platform: + +.. code:: console + + $ tools/sethost.sh -c + +Other options are available: + +.. code:: console + + $ ./sethost.sh -h + + USAGE: ./sethost.sh [-l|m|c|g|n] [make-opts] + ./sethost.sh -h + + Where: + -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), + MSYS/MSYS2 (g) or Windows native (n). Default Linux + make-opts directly pass to make + -h will show this help test and terminate diff --git a/Documentation/components/tools/showsize.rst b/Documentation/components/tools/showsize.rst new file mode 100644 index 00000000000..effcd07611e --- /dev/null +++ b/Documentation/components/tools/showsize.rst @@ -0,0 +1,14 @@ +=============== +``showsize.sh`` +=============== + +Show the top 10 biggest memory hogs in code and data spaces. This must be +executed from the top-level NuttX directory like: + +.. code:: console + + $ tools/showsize.sh + TOP 10 BIG DATA + ... + TOP 10 BIG CODE + ... diff --git a/Documentation/components/tools/simbridge.rst b/Documentation/components/tools/simbridge.rst new file mode 100644 index 00000000000..6eb5e4368ab --- /dev/null +++ b/Documentation/components/tools/simbridge.rst @@ -0,0 +1,15 @@ +================ +``simbridge.sh`` +================ + +Helper script used to set up a bridge to support networking with the +simulator under Linux. + +General usage: + +.. code:: console + + $ tools/simbridge.sh + Usage: tools/simbridge.sh + +See ``boards/sim/sim/sim/NETWORK-LINUX.txt`` for further information. diff --git a/Documentation/components/tools/simhostroute.rst b/Documentation/components/tools/simhostroute.rst new file mode 100644 index 00000000000..11f8b4dbffa --- /dev/null +++ b/Documentation/components/tools/simhostroute.rst @@ -0,0 +1,15 @@ +=================== +``simhostroute.sh`` +=================== + +Helper script used to set up the tap driver, host routes, and IP Tables rules to +support networking with the simulator under Linux. + +General usage: + +.. code:: console + + $ tools/simhostroute.sh + Usage: tools/simhostroute.sh + +See ``boards/sim/sim/sim/NETWORK-LINUX.txt`` for further information. diff --git a/Documentation/components/tools/testbuild.rst b/Documentation/components/tools/testbuild.rst new file mode 100644 index 00000000000..ea568ced6db --- /dev/null +++ b/Documentation/components/tools/testbuild.rst @@ -0,0 +1,75 @@ +================ +``testbuild.sh`` +================ + +This script automates building of a set of configurations. The intent is +simply to assure that the set of configurations build correctly. The -h +option shows the usage: + +.. code:: console + + $ ./testbuild.sh -h + USAGE: tools/testbuild.sh -h [-l|m|c|g|n] [-d] [-e ] [-x] [-j ] [-a ] [-t ] [-p] + [-A] [-C] [-G] [-N] [-R] [-S] [--codechecker] + + Where: + -h will show this help test and terminate + -l|m|c|g|n selects Linux (l), macOS (m), Cygwin (c), + MSYS/MSYS2 (g) or Windows native (n). Default Linux + -d enables script debug output + -e pass extra c/c++ flags such as -Wno-cpp via make command line + -x exit on build failures + -j passed on to make. Default: No -j make option. + -a provides the relative path to the apps/ directory. Default ../apps + -t provides the absolute path to top nuttx/ directory. Default ../nuttx + -p only print the list of configs without running any builds + -A store the build executable artifact in ARTIFACTDIR (defaults to ../buildartifacts + -C Skip tree cleanness check. + -G Use "git clean -xfdq" instead of "make distclean" to clean the tree. + This option may speed up the builds. However, note that: + * This assumes that your trees are git based. + * This assumes that only nuttx and apps repos need to be cleaned. + * If the tree has files not managed by git, they will be removed + as well. + -N Use CMake with Ninja as the backend. + -R execute "run" script in the config directories if exists. + -S Adds the nxtmpdir folder for third-party packages. + --codechecker enables CodeChecker statically analyze the code. + selects the list of configurations to test. No default + + Your PATH variable must include the path to both the build tools and the + kconfig-frontends tools + +This script needs two pieces of information: + +1. A description of the platform that you are testing on. This description + is provided by the optional -l, -m, -c, -g and -n options. + +2. A list of configurations to build. That list is provided by a test + list file. The final, non-optional parameter, , + provides the path to that file. + +The test list file is a sequence of build descriptions, one per line. One +build descriptions consists of two comma separated values. For example:: + + stm32f429i-disco:nsh + arduino-due:nsh + /arm + /risc-v + +The first value is the usual configuration description of the form +``:`` or ``/`` and must correspond to a +configuration or folder in the nuttx/boards directory. + +The second value is valid name for a toolchain configuration to use +when building the configuration. The set of valid toolchain +configuration names depends on the underlying architecture of the +configured board. + +The prefix ``-`` can be used to skip a configuration:: + + -stm32f429i-disco/nsh + +or skip a configuration on a specific host(e.g. Darwin):: + + -Darwin,sim:rpserver diff --git a/Documentation/components/tools/uncrustify.rst b/Documentation/components/tools/uncrustify.rst new file mode 100644 index 00000000000..c98fcf68f0f --- /dev/null +++ b/Documentation/components/tools/uncrustify.rst @@ -0,0 +1,69 @@ +================== +``uncrustify.cfg`` +================== + +This is a configuration script for the uncrustify code beautifier. +Uncrustify does well with forcing braces into "if" statements and +indenting per the NuttX C coding standard. It correctly does things +like placing all braces on separate lines at the proper indentation +level. It cannot handle certain requirements of the coding standard +such as + +- FAR attributes in pointer declarations. +- The NuttX standard function header block comments. +- Naming violations such as use of CamelCase variable names, + lower case pre-processor definitions, etc. + +Comment blocks, function headers, files headers, etc. must be formatted +manually. + +Its handling of block comments is fragile. If the comment is perfect, +it leaves it alone, but if the block comment is deemed to need a fix +it starts erroneously indenting the continuation lines of the comment. + +- uncrustify.cfg messed up the indent of most block comments. + cmt_sp_before_star_cont is applied inconsistently. I added:: + + cmt_indent_multi = false # disable all multi-line comment changes + + to the .cfg file to limit its damage to block comments. +- It is very strict at wrapping lines at column 78. Even when column 79 + just contained the ``/`` of a closing ``*/``. That created many + bad continuation lines. + +- It moved '{' that opened a struct to the line defining the struct. + nl_struct_brace = add (or force) seemed to be ignored. + +- It also aligned variable names in declarations and '=' signs in + assignment statements in a seemingly arbitrary manner. Making changes + that were not necessary. + +.. note:: + + uncrustify.cfg should **ONLY** be used with new files that have an + inconsistent coding style. uncrustify.cfg should get you in the ballpark, + but you should expect to review and hand-edit the files to assume 100% + compliance. + +.. warning:: + + **NEVER** use uncrustify.cfg for modifications to existing NuttX files. It + will probably corrupt the style in subtle ways! + +This was last verified against uncrustify 0.66.1 by Bob Feretich. + +About uncrustify: Uncrustify is a highly configurable, easily modifiable +source code beautifier. To learn more about uncrustify: + + http://uncrustify.sourceforge.net/ + +Source code is available on GitHub: + + https://github.com/uncrustify/uncrustify + +Binary packages are available for Linux via command line installers. +Binaries for both Windows and Linux are available at: + + https://sourceforge.net/projects/uncrustify/files/ + +See also :doc:`/components/tools/indent` and :doc:`/components/tools/nxstyle`. diff --git a/Documentation/components/tools/zds.rst b/Documentation/components/tools/zds.rst new file mode 100644 index 00000000000..36628f894ef --- /dev/null +++ b/Documentation/components/tools/zds.rst @@ -0,0 +1,6 @@ +=== +zds +=== + +This directory contains build tools used only with the ZDS-II +platforms (z8, ez80, zNeo). diff --git a/Documentation/components/tools/zipme.rst b/Documentation/components/tools/zipme.rst new file mode 100644 index 00000000000..d00f9c24699 --- /dev/null +++ b/Documentation/components/tools/zipme.rst @@ -0,0 +1,27 @@ +============ +``zipme.sh`` +============ + +I use this script to create the nuttx-xx.yy.tar.gz tarballs for +release. It is handy because it also does the kind of clean up +that you need to do to make a clean code release. +It can also PGP sign the final tarballs and create their SHA512 hash. +Any VCS files or directories are excluded from the final tarballs. + +Help: + +.. code:: console + + $ ./tools/zipme.sh -h + USAGE="USAGE: ./tools/zipme.sh [-d|h|v|s] [-b [-e ] [-k ] []" + +Examples: + +.. code:: console + + $ ./tools/zipme.sh -s 9.0.0 + # Create version 9.0.0 tarballs and sign them. + $ ./tools/zipme.sh -s -k XXXXXX 9.0.0 + # Same as above but use the key-id XXXXXX to sign the tarballs + $ ./tools/zipme.sh -e "*.swp tmp" 9.0.0 + # Create the tarballs but exclude any .swp file and the "tmp" directory.