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)