nescc(1)

📦 version 1.3.5, in debian bookworm, ubuntu jammy

💖 nescc — the nesC compiler, bestie edition 💖

okay so hi, you found the man page for nescc(1), straight outta the General Commands Manual. pull up a chair, grab a boba, we're doing this. 🧋✨

✨ NAME ✨

nescc — the nesC compiler. that's it, that's the name. iconic. 👑

🌸 SYNOPSIS 🌸

nescc [-gcc=gcc-name] [-fnesc-gcc=gcc-name] [-fnesc-mingw-gcc]
    [-fnesc-target=architecture] [-fnesc-docdir=dir]
    [-fnesc-topdir=dir] [-fnesc-docs-use-graphviz] [-fnesc-is-app]
    [-fnesc-simulate]
    [-fnesc-nido-tosnodes=n] [-fnesc-nido-motenumber=expression]
    [-conly] [-fnesc-cfile=file] [-fnesc-gccize]
    [-fnesc-cppdir=directory] [-fnesc-separator=separator]
    [-fnesc-no-inline] [-fnesc-optimize-atomic]
    [--version] [-fnesc-include=file] [-fnesc-verbose] [-Wnesc-...]
    [-fnesc-dump=specification] [-fnesc-dumpfile=file]
    [-fnesc-scheduler=specification] [-fnesc-path=path]
    [-fnesc-no-debug]
    [-fnesc-deputy] [-fnesc-no-deputy]
    [-fnesc-default-safe] [-fnesc-default-unsafe]
    [any gcc option] files...

🦋 DESCRIPTION 🦋

okay so nescc is basically gcc but with ✨extensions✨ — it knows how to compile nesC applications. that's the whole vibe.

  • if you invoke it on regular C files? it behaves exactly like gcc. no notes, no drama. 💅
  • if you invoke it on a nesC component or interface file (that's the .nc extension, babes), it compiles and links that component together with the other files you listed on the command line.
but wait — it does not link if you're using the -c, -S, -conly, -E or -fsyntax-only options. read the room, read your flags. 🫶

💅 OPTIONS 💅

so nescc accepts every single gcc option, plus a whole little collection of nesC-specific ones. here we go, bestie:

  • -gcc=gcc-name, -fnesc-gcc=gcc-name — tell it which gcc compiler to use for compiling and linking any C files, whether those were explicitly specified by you or generated as the output of the nesC-to-C compiler. this option is what supports cross-compilation of nesC code (which is, like, the usual mode of operation...).
  • -fnesc-mingw-gcc — pass this if the gcc version you specified with -gcc=... was compiled for Window's mingw environment. in that case it expects Windows-style paths rather than Unix-style paths. so different. so specific. 🪟
  • -fnesc-target=architecture — say which target architecture to compile for. currently supported platforms are avr (the Atmel AVR family), msp430 (the TI MSP430 family) and self (the machine the nesC compiler is running on). if you use the env target, the architecture details get read from the NESC_MACHINE environment variable instead. see the separate env target documentation for the deets.
  • -fnesc-docdir=dir — generate documentation for the compiled component, and put it in directory dir.
  • -fnesc-topdir=dir — specify directory paths that should be stripped from the source file names when generating "package names" for the documentation files.
  • -fnesc-docs-use-graphviz — explicitly enable or disable the use of the graphviz tool in the generated documentation. without this option, graphviz is enabled iff the dot program is found in the current path. heads up: using graphviz requires dot. the documentation generation tool also checks the version of dot, and enables client-side image maps if they're supported. fancy. 🎀
  • -fnesc-is-app — tell nescc that the source being compiled is an application, and that it should generate an app description page for the entire application. main character application energy.
  • -fnesc-simulate — compile for a simulation environment.
  • -fnesc-nido-tosnodes=n, -fnesc-nido-motenumber=expression — when -fnesc-simulate is specified, the nesC program is compiled for a simulation environment where a single executable will simulate n nodes. specifically: in the generated code, each global variable becomes an n element array, and all accesses to global variables are indexed with expression. so yeah, one binary, many little guys. 🐣
  • -conly — just compile to C, leaving the generated source code for top-level-component comp.nc in the C file comp.c (except if the -fnesc-cfile option is specified).
  • -fnesc-cfile=file — specify a file in which to save the C code generated when compiling a component.
⚠️ note: if you specify two components on the command line, then the C code from the second one will overwrite the C code from the first. the second one said "my turn". 💀
  • -fnesc-gccize — output target-specific extensions as gcc-style attributes rather than using the target's original syntax. this can help if you're using -conly and sending the nesC output off to some other tool that understands gcc attributes but not the target-specific extensions.
  • -fnesc-cppdir=directory — save all preprocessing results in directory. the directory gets created if it doesn't exist. this can be helpful for tracking down preprocessor-related compilation problems. you probably want to make sure directory is empty when you call nescc, so it's obvious which files were preprocessed as part of the current compilation. detective mode 🔍
  • -fnesc-separator=separator — set the separator used to create symbol names in the generated C code (default is $). the compiler needs to generate unique names to denote stuff like, e.g., a module variable, and it does that by concatenating various symbol names to make sure the names come out unique. for instance, variable bar in module Maz becomes a global C variable Maz$bar in the compiler output. some C compilers do not like $ in symbol names, so you can specify a different separator, e.g., __ (which leads to generated symbols like Maz__bar).
🚨 you will get a compile-time warning if any symbol in the program being compiled contains the separator you specify — because the presence of the separator in a symbol could lead to the generation of incorrect code. the separator can, however, start or end a symbol.
  • -fnesc-no-inline — disables the automatic inlining of all small functions, and of all functions with a single call site.
  • -fnesc-optimize-atomic — optimize atomic statements [EXPERIMENTAL]: reduce or remove the overhead of atomic statements in simple cases (e.g., single-byte reads). experimental means experimental, bestie, don't come for me. 🧪
  • --version — print the version of nescc and of the selected gcc compiler (see -gcc).
  • -fnesc-include=header-file — include the specified file before compiling a nesC component. it behaves as if includes header-file; was included at the start of that component. (and yes, the synopsis calls it file while this option says header-file — we contain multitudes. 🙈)
  • -fnesc-dump=specification — output information on the compiled program's structure, and in particular its user-specified attributes. for more details, see the separate nesC dump documentation.
  • -fnesc-dumpfile=file — where to output the information requested by -fnesc-dump. defaults to stdout.
  • -fnesc-verbose — be more verbose than -v. yes. more. than that. 📢
  • -fnesc-scheduler=component,unique-string,interface-name,interface-definition,run-event,post-command — okay so by default, nesC compiles uses of task void taskname() ... to void taskname(), and post taskname() to TOS_post(taskname).

with this option, each task gets its own interface-definition interface, the task implementation is transformed into a run-event event, and posts becomes a call to the post-command command. this per-task interface is automatically connected to the parameterised interface-name interface of scheduler component component. the parameter id for the connection is chosen with unique("unique-string"). slay. 🎯

  • -fnesc-path=path — add colon separated directories to the nescc search path.
  • -fnesc-no-debug — remove the functions dbg(), dbg_clear(), dbg_active() from the source code.
  • -fnesc-deputy — compile with the deputy compiler.
  • -fnesc-no-deputy — do not use the deputy compiler. this is the default.
  • -fnesc-default-safe — make modules default to having the @safe() attribute. has no effect if -fnesc-deputy is not set.
  • -fnesc-default-unsafe — make modules default to having the @unsafe() attribute. has no effect if -fnesc-deputy is not set.

⭐ the nesC-specific warnings ⭐

there are a number of warnings specific to nesC, specified with -Wnesc-. and listen: all of these warnings are off by default. every single one. 💤

  • -Wnesc-fnptr — warn when function pointers are used. (use of function pointers is deprecated in nesC and leads to inaccurate data race detection.)
  • -Wnesc-async — warn when interrupt handlers call commands or events that are not annotated with async.
  • -Wnesc-data-race — warn about potential data races.
  • -Wnesc-combine — warn when configuration wiring leads to "fan-out" and the function return type does not have a combining function defined.
  • -Wnesc-docstring — warn when unexpected documentation strings (starting with /**) are seen.
  • -Wnesc-implicit-conn — warn when implicit connections between components are used.
  • -Wnesc-all — turns on -Wnesc-fnptr, -Wnesc-async, -Wnesc-combine and -Wnesc-data-race.
  • -Wnesc-error — turns the -Wnesc-fnptr, -Wnesc-async, -Wnesc-combine and -Wnesc-data-race warnings into errors. 🔥

🌈 and also, the gcc-isms 🌈

when compiling a nesC component, the nesC compiler recognizes the gcc C language (-f...) and warning (-W...) options. the -S, -c and -o options work as usual, and the -x option accepts nesc. the -v option causes the nesC compiler to print out the paths of all components and interfaces that are loaded. directories can be added to nesC's search path with -I.

🎀 EXAMPLES 🎀

if you wish to compile a component Bar.nc to a C file, you can do:

nescc -c -o /dev/null -fnesc-cfile=Bar.c Bar.nc

that's it, that's the whole move. /dev/null said "not today" and Bar.c said "say less". 🍓

💜 PREPROCESSOR SYMBOLS 💜

nescc defines the following preprocessor symbol:

  • NESC (since v1.1) — set to XYZ where x.yz is the nesC version.

🌸 ENVIRONMENT VARIABLES 🌸

  • NESCPATH — a colon separated list of additional search directories for nesC components.

✨ SEE ALSO ✨

gcc(1), platform-specific gcc

💀 NOTES 💀

the warnings for the new nesC 1.1 features (see -Wnesc-all) are off by default to increase compatibility with nesC 1.0 code. so if you want to match the language specification in the nesC 1.1 reference manual, you should compile with -Wnesc-all and -Wnesc-error. these options will become the default in future releases. so like... get used to them now, bestie. 👑

and that's the page!! 🦋 this whole thing is from the General Commands Manual and it's dated May 22, 2013 — so if you're reading this in the future, hi, hope nescc is treating you well. go compile something cute. 💖✨

📦 where this page comes from