NAME

       nescc - nesC compiler

SYNOPSIS

       nescc [-gcc=gcc-name] [-mingw-gcc] [-fnesc-target=architecture]
           [-docdir=dir] [-topdir=dir] [-graphviz=y|n]
           [-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-verbose] [-Wnesc-...]
           [-fnesc-dump=specification] [-fnesc-dumpfile=file]
           [-fnesc-scheduler=specification]
           [any gcc option] files...

DESCRIPTION

       nescc  is an extension to gcc that knows how to compile nesC applications. If invoked on regular C files,
       it behaves exactly like gcc. When invoked on a nesC  component  or  interface  (.nc  extension)  file  it
       compiles  and  links  (except if the -c, -S, -conly, -E or -fsyntax-only options are used) that component
       with the other files specified on the command line.

OPTIONS

       nescc accepts all gcc options, and some additional nesC specific options:

       -gcc=gcc-name
              Specify which gcc compiler to use to compile and link any C files, either explicitly specified, or
              generated as the output of the nesC-to-C compiler.  This option supports cross-compilation of nesC
              code (the usual mode of operation...).

       -mingw-gcc
              Pass this option if the gcc version specified  with  -gcc=...  was  compiled  for  Window's  mingw
              environment, and hence expects Windows-style rather than Unix-style paths.

       -fnesc-target=architecture
              Specify  the  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 are read from the NESC_MACHINE environment
              variable. See the separate env target documentation for details.

       -docdir=dir
              Generate documentation for the compiled component in directory dir.

       -topdir=dir
              Specify directory paths that should be  stripped  from  the  source  file  names  when  generating
              "package names" for the documentation files.

       -graphviz=y|n
              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. Use of graphviz
              requires  dot.   The  documentation generation tool checks the version of dot, and enables client-
              side image maps, if supported.

       -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.

       -conly Just  compile  to  C,  leaving the generated source code for top-level-component comp.nc in 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.

       -fnesc-gccize
              Output target-specific extensions as gcc-style attributes rather than using the target's  original
              syntax. Can help if using -conly and sending the nesC output from some other tool that understands
              gcc attributes but not the target-specific extensions.

       -fnesc-cppdir=directory
              Save all preprocessing results in directory. The directory is created if it  doesn't  exist.  This
              can  be  helpful  to  track  down  preprocessor-related compilation problems. You probably want to
              ensure that directory is empty when  you  call  nescc,  to  make  it  obvious  which  files  where
              preprocessed as part of the current compilation.

       -fnesc-separator=separator
              Set separator used to create symbol names in the generated C code (default $).  The compiler needs
              to generate unique names to denote, e.g., a module variable. It does this by concatenating various
              symbol  names  to  ensure that it generates unique names. 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., __ (leading 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 (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
              Disabled 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).

       --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. Behaves as if includes  header-file;
              was included at the start of that component.

       -fnesc-dump=specification
              Output  information  on  the  compiled  programs  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.

       -fnesc-scheduler=component,unique-string,interface-name,interface-definition,run-event,post-command
              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").

       There  are  a  number of warnings specific to nesC, specified with -Wnesc- (all these warnings are off by
       default):

       -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 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-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.

       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, 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 nesCs 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

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. 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.

                                                 April 27, 2004                                         nescc(1)