.TH ncc 1 "April 27, 2004".LO 1.SH NAMEncc - nesC compiler for TinyOS.SH SYNOPSIS\fBncc\fR [\fB-target=\fIpc|mica|mica2|mica2dot|...\fR] [\fB-print-platforms\fR]    [\fB-board=\fImicasb|basicsb|micawb|...\fR]    [\fB-tosdir=\fIdir\fR] [\fB-print-tosdir\fR] [\fB-nostdinc\fR]     [\fB-docdir=\fIdir\fR] [\fB-topdir=\fIdir\fR] [\fB-graphviz=y\fI|\fBn\fR]    [\fB-fnesc-nido-tosnodes=\fIn\fR] [\fB-fnesc-cfile=\fIfile\fR] [\fB-fnesc-no-inline\fR]    [\fB--version\fR] [\fB-fnesc-verbose\fR] [\fB-Wnesc-\fI...\fR]    [\fB-fnesc-dump=\fIspecification\fR] [\fB-fnesc-dumpfile=\fIfile\fR]    [\fB-fnesc-scheduler=\fIspecification\fR]    [any gcc option] \fIfiles\fR....SH DESCRIPTION\fBncc\fR is an extension to \fBgcc\fR that knows how to compile nesCapplications in the TinyOS environment. If invoked on regular C files, itbehaves exactly like \fBgcc\fR. When invoked on a nesC component orinterface (\fB.nc\fR extension) file it compiles and links (except if theusual \fB-c\fR, \fB-S\fR, \fB-E\fR or \fB-fsyntax-only\fR options are used)that component with the other files specified on the command line..SH OPTIONS\fBncc\fR accepts all \fBgcc\fR options, and some additional TinyOSand nesC specific options:.TP\fB-target=\fIX\fR Specify the target architecture for this compilation. If \fBpc\fR isspecified, the compilation uses the tossim environment and produces alocally executable file. The default target is \fBmica\fR, the possibletargets are set by the TinyOS distribution (see the \fBtos/platforms\fRdirectory). A platform that is not in the TinyOS distribution can be usedif its directory is specified with an explicit -I directive (the platformname is taken from the directory's name, platform directories arerecognised by the presence of a \fB.platform\fR file)..TP\fB-tosdir=\fIdir\fR Specify the location of TinyOS. This location can also be specified withthe \fBTOSDIR\fR environment variable. If the variable and the option are bothgiven, \fBncc\fR uses the value specified with the option. If neither theenvironment variable or option are specified, ncc uses its compiled-inTinyOS directory..TP\fB-print-tosdir\fRPrint the TinyOS directory to be used and exit, taking into account the\fB-tosdir\fR option and \fBTOSDIR\fR environment variable. No compilationoccurs when \fB-print-tosdir\fR is used..TP\fB-print-platforms\fRPrint the valid TinyOS platforms, including those made available byexplicit \fB-I\fR directives (see \fB-target\fR option)..TP\fB-nostdinc\fRDo not automatically include the TinyOS directories in the search path. Seethe discussion of search paths below for more details..TP\fB-board=\fIY\fRSpecify one (or more) sensor boards. This effects the search path andpreprocessor symbols. The set of boards is set by the TinyOS distribution(see the \fBtos/sensorboards\fR directory). As with targets, a sensorboarddirectory can be made available via an explicit \fB-I\fR directive(sensorboard directories are recognised by the presence of a \fB.sensor\fRfile)..TP\fB-docdir=\fIdir\fR Generate documentation for the compiled component in directory \fIdir\fR..TP\fB-topdir=\fIdir\fR Specify directory paths that should be stripped from the source file nameswhen generating "package names" for the documentation files.  The directoryabove \fBTOSDIR\fR is automatically added, so this option is only needed fordirectories outside the main TinyOS distribution..TP\fB-graphviz=y\fR|\fBn\fR Explicitly enable or disable the use of the graphviz tool in the generateddocumentation. Without this option, graphviz is enabled iff the \fBdot\fRprogram is found in the current path. Use of graphviz requires \fBdot\fR.  Thedocumentation generation tool checks the version of \fBdot\fR, and enablesclient-side image maps, if supported..TP\fB-fnesc-nido-tosnodes=\fIn\fR Specify the maximum number of nodes that can be simulated in the tossim(\fBpc\fR target) environment..TP\fB-fnesc-no-inline\fRDisabled the automatic inlining of all small functions, and of all functionswith a single call site..TP\fB-fnesc-cfile=\fIfile\fR Specify a file in which to save the C code generated when compiling acomponent. Note: if you specify two components on the command line, thenthe C code from the second one will overwrite the C code from the first..TP\fB--version\fRPrint the version of \fBncc\fR, \fBnescc\fR and of the gcc compilerused for the selected target..TP\fB-fnesc-include=\fIheader-file\fRInclude the specified file before compiling a nesC component. Behavesas if \fBincludes \fIheader-file\fB;\fR was included at the start ofthat component..TP\fB-fnesc-dump=\fIspecification\fROutput information on the compiled programs structure, and in particularits user-specified attributes. For more details, see the separate nesCdump documentation..TP\fB-fnesc-dumpfile=\fIfile\fRWhere to output the information requested by \fB-fnesc-dump\fR. Defaults tostdout..TP\fB-fnesc-verbose\fRBe more verbose than \fB-v\fR..TP\fB-fnesc-scheduler=\fIcomponent\fR,\fIunique-string\fR,\fIinterface-name\fR,\fIinterface-definition\fR,\fIrun-event\fR,\fIpost-command\fRBy default, nesC compiles uses of \fBtask void \fItaskname\fB() ...\fR to\fBvoid \fItaskname\fB()\fR, and \fBpost \fItaskname()\fR to\fBTOS_post(\fItaskname\fB)\fR. With this option, each task gets its own \fIinterface-definition\fRinterface, the task implementation is transformed into a \fIrun-event\fRevent and posts becomes a call to the \fIpost-command\fR command. Thisper-task interface is automatically connected to the parameterised\fIinterface-name\fR interface of scheduler component \fIcomponent\fR. Theparameter id for the connection is chosen with\fBunique("\fIunique-string\fB")\fR..PPThere are a number of warnings specific to nesC, specified with\fB-Wnesc-\fR (all these warnings are off bydefault):.TP\fB-Wnesc-fnptr\fRWarn when function pointers are used (use of function pointers isdeprecated in nesC and leads to inaccurate data race detection)..TP\fB-Wnesc-async\fR Warn when interrupt handlers call commands or events not annotated with\fBasync\fR..TP\fB-Wnesc-data-race\fRWarn about potential data races..TP\fB-Wnesc-combine\fRWarn when configuration wiring leads to "fan-out" and the function returntype does not have a combining function defined..TP\fB-Wnesc-docstring\fRWarn when unexpected documentation strings (starting with \fB/**\fR) areseen..TP\fB-Wnesc-all\fRTurns on \fB-Wnesc-fnptr\fR, \fB-Wnesc-async\fR, \fB-Wnesc-combine\fR and\fB-Wnesc-data-race\fR..TP\fB-Wnesc-error\fRTurns the \fB-Wnesc-fnptr\fR, \fB-Wnesc-async\fR, \fB-Wnesc-combine\fR and\fB-Wnesc-data-race\fR warnings into errors..PPWhen compiling a nesC component, the nesC compiler recognizes the gcc Clanguage (\fB-f...\fR) and warning (\fB-W...\fR) options. The \fB-S\fR,\fB-c\fR and \fB-o\fR options work as usual, the \fB-x\fR option accepts\fBnesc\fR. The \fB-v\fR option causes the nesC compiler to print out thepaths of all components and interfaces that are loaded. Directories can beadded to nesC\fRs search path with \fB-I\fR (see the search path discussionbelow)..SH EXAMPLESIf you wish to compile a component Bar.nc to a C file, you can do:.IPncc -c -o /dev/null -fnesc-cfile=Bar.c Bar.nc.SH SEARCH PATH\fBncc\fR performs the following substitutions on the directories specifiedwith the \fB-I\fR option: \fB%T\fR is replaced by the TinyOS directory,\fB%p\fR is replaced by the selected target, \fB%%\fR is replaced by\fB%\fR.Except when \fB-nostdinc\fR is specified, the search path for nesCcomponents is as follows, where \fItosdir\fR is the TinyOS directoryrequested and \fItarget\fR is the selected target:.IP *The current directory.IP *\fB-I\fR directives (in option order).IP *%T/sensorboards/\fIboardname\fR, for each\fB-board=\fIboardname\fR option specified (in option order) -except if the sensorboard was found via an explicit -I directive.IP *%T/platform/%p  - except if the platform was found via anexplicit -I directive.IP *Additional directories requested by the selected target (e.g.,%T/platform/avrmote for the mica target).IP *%T/interfaces.IP *%T/system.IP *%T/lib.IP *\fBNESCPATH\fR environment variable directories (note that %T and %psubsitution is not performed on these directories)..PPWhen \fB-nostdinc\fR is specified, the search path is simply:.IP *The current directory.IP *\fB-I\fR directives.IP *\fBNESCPATH\fR environment variable directories.SH PREPROCESSOR SYMBOLS\fBncc\fR defines the following preprocessor symbols:.TP\fBNESC\fR (since v1.1) set to XYZ where x.yz is the nesC version.TP\fBPLATFORM_\fItarget\fR where \fItarget\fR is the selected target name, converted to upper case.TP\fBBOARD_\fIboardname\fR for each \fB-board=\fIboardname\fR option (theboardname is converted to upper case).SH ENVIRONMENT VARIABLES.TP.B TOSDIRIf the \fB-tosdir=\fIdir\fR option is not used, the \fBTOSDIR\fRenvironment variable specifies the location of TinyOS..TP.B NESCPATH A colon separated list of additional search directories fornesC components..SH SEE ALSO.IR gcc (1),platform-specific gcc,.IR nescc (1).SH NOTES\fBncc\fR is built over \fBnescc\fR, which handles the non-TinyOS-specificfunctionality of \fBncc\fR. Users of nesC in a non-TinyOS context mayprefer to use \fBnescc\fR (see the source code of ncc and nescc fordetails).The warnings for the new nesC 1.1 features (see \fB-Wnesc-all\fR) are offby default to increase compatibility with nesC 1.0 code. To match thelanguage specification in the nesC 1.1 reference manual, you should compilewith \fB-Wnesc-all\fR and \fB-Wnesc-error\fR. These options will become thedefault in future releases.