.. program:: xcc

.. _xcc_manual:

XCC
===

Synopsis
--------

.. code-block::

   xcc [-c|-S|-E] [-g] [-O<level>]
       [-W<warn>...]
       [-I<dir>...] [-L<dir>...]
       [-D<macro>[=<defn>]]
       [-f<option>...]
       [-target=<platform>]
       [-o <outfile>] infile

Only the most useful options are listed here; see below for the remainder.

Description
-----------

XCC is deliberately analogous to GCC and imitates many of its behaviours. XCC 
is a wrapper around a collection of tools to make the use of those tools 
simpler. Those tools perform the steps of preprocessing, compilation (both
C/C++ and XC), assembly and 'mapping'. Those tools may be used 
individually, but are more easily used via xcc.

XCC will normally run all of the steps. The first three steps are similar to 
GCC in that they are applied to an individual source file to produce an object 
file. The 'mapping' step, as the name suggests, is different. Rather than 
producing an executable for a single processor, the linker is invoked multiple 
times to produce an executable per processor. Furthermore, the process 
includes auto-generating source code, compiling it and invoking the linker 
further times. The resulting single output file is an :ref:`XE file<xe_format>`
, which contains the multiple executables.

Options such as :option:`-c`, :option:`-S` and :option:`-E` prevent all the 
steps running, and instead produce an intermediate output.

No matter which step is being performed, a platform conforming to the
:ref:`xn_spec` must be specified. This is done via
:envvar:`XCC_DEFAULT_TARGET`, :option:`-target` or, better, listed as one of 
the input files.

During compilation of a program, the compiler generates a temporary
header file named :file:`platform.h` that contains variable and macro
definitions, as defined by the target XN file, which include:

 * Declarations of variables of type ``tileref`` (see :ref:`xn_spec_declaration`).
 * Macro definitions of port names (see :ref:`xn_spec_port`).

Many options are passed directly through to the tool performing the 
processing step. For instance, some options directly influence the behaviour 
of the compiler or the linker.

For the most part, the order you use for the options doesn't matter. Order 
does matter when you use several options of the same kind; for example, if you 
specify :option:`-L` more than once, the directories are searched in the order 
specified. In other cases, such as with :option:`-O` repeated usage will 
result in the rightmost usage to take precedence.

Many options have negative forms (for example, ``-fno-<option>``).

A space between an option and its argument is permitted.

Options
-------

Overall Options
^^^^^^^^^^^^^^^

.. option:: -x <language>

    Overrides default handling for the following input files. This option
    applies to all following input files until the next :option:`-x` option.
    Supported values for `language` are:

      - ``xc``
      - ``c``
      - ``c++``
      - ``assembler``
      - ``assembler-with-cpp``
      - ``xn``
      - ``xscope``
      - ``none`` (turn off language specification)

    Default handling of the input files is determined by their suffix:

    .. list-table:: File extensions recognized by XCC and their meaning
     :header-rows: 1
     :widths: 20 45 35

     * -  Extension
       -  Type of File
       -  Preprocessed by XCC
     * -  ``.xc``
       -  XC source code
       -  Y
     * -  ``.c``
       -  C source code
       -  Y
     * -  ``.cpp``
       -  CPP source code (for compatability, the extensions ``cc``, ``cp``, ``c++``, ``C`` and ``cxx`` are also recognized)
       -  Y
     * -  ``.S``
       -  Assembly code
       -  Y
     * -  ``.xscope``
       -  xSCOPE configuration file
       -  N
     * -  ``.xn``
       -  xCORE Network Description
       -  N
     * -  ``.xi``
       -  XC source code
       -  N
     * -  ``.i``
       -  C source code
       -  N
     * -  ``.ii``
       -  C++ source code
       -  N
     * -  ``.s``
       -  Assembly code
       -  N
     * -  *other*
       -  Object file .o be given to the linker
       -  N

.. option:: -std=<standard>

   Specifies the language variant for the following input C or C++
   file. Supported values for ``<standard>`` are:

   ``c89``
     ISO C89
   ``gnu89``
     ISO C89 with GNU extensions
   ``c99``
     ISO C99
   ``gnu99``
     ISO C99 with GNU extensions (default for C programs)
   ``c++98``
     ISO C++ (1998)
   ``gnu++98``
     ISO C++ (1998) with GNU extensions (default for C++ programs)

.. option:: -fsubword-select

    In XC, allows selecting on channel inputs where the size of
    the desstination variable is less than 32 bits.
	
    This is default for targets based on XS1-L devices. It is not
    default for targets based on XS1-G devices. For further details,
    see :ref:`xs1_target_behavior_channel_communication`.
		 
.. option:: -target=<platform>
     
    Convenience mechanism for specifying a pre-canned target platform. The 
    platform configuration must be specified in the file 
    :file:`{platform}.xn`, which is searched for in the paths specified by the 
    :envvar:`XCC_TARGET_PATH` environment variable.

    The use of this option is not recommended for long-lived projects due to 
    the likelihood of the target platform changing in an uncontrolled fashion.
    It is best practice to specify a platform explicitly by defining and 
    supplying a target platform as one of the xcc input files. For example::

       $ xcc my_target.xn main.c

.. option:: -foverlay

    Enable support for memory overlays. Functions marked as overlay roots are
    placed in external memory and are loaded on demand at runtime. The option
    should be passed when compiling and linking. An overlay runtime should be
    supplied in the application.

.. option:: -foverlay=flash

    Enable support for memory overlays linking in the flash overlay runtime.
    Overlays are only enabled on tiles which boot from flash.

.. option:: -foverlay=syscall

    Enable support for memory overlays linking in the syscall overlay runtime.
    Overlay are enabled on all tiles. Overlays are loaded from a host machine
    using a system call.

.. option:: -fxscope[=link|uart]
     
    Enable support for tracing using xSCOPE (defaults to link). The XN file of 
    the target must contain an xSCOPE link. The option should be passed when 
    compiling and linking.
     
.. option:: -fcmdline-buffer-bytes=<n>

   Add a buffer of size <n> bytes to be used to hold command line arguments.

.. option:: -pass-exit-codes
     
    Returns the numerically highest error code produced by any phase of
    compilation. (By default XCC returns 1 if any phase of the compiler
    returns non-success, otherwise it returns 0.)

.. option:: -c
     
    Compiles or assembles the source files, producing an object file
    for each source file, but does not link/map. By default the object
    filename is formed by replacing the source file suffix with ``.o``
    (for example, :file:`{a}.c` produces :file:`{a}.o`).

.. option:: -S
     
    Stops after compilation proper, producing an assembly code file for
    each nonassembly input file specified. By default the assembly
    filename is formed by replacing the source file suffix with .s.
     
    Input files not requiring compilation are ignored.

.. option:: -E
     
    Preprocesses the source files only, outputting the preprocessed
    source to stdout.
     
    Input files not requiring preprocessing are ignored.

.. option:: -o <file>
     
    Places output in :file:`file`.
     
    If :option:`-o` is not specified, the executable file is placed in
    :file:`a.xe`, the object file for :file:`{source}.suffix` in :file:`{source}.o`,
    its assembly code file in :file:`{source}.s`, and all preprocessed
    C/C++/XC source on standard output.

.. option:: -v
     
    Prints (on standard error) the commands executed at each stage of
    compilation. Also prints the version number of XCC, the
    preprocessor and the compiler proper.

.. option:: -###
     
    The same as :option:`-v` except that the commands are not executed and
    all command arguments are quoted.

.. option:: --help
     
    Prints a description of the supported command line options. If
    :option:`-v` is also specified, :option:`--help` is also passed to the
    subprocesses invoked by XCC.

.. option:: --version
     
    Displays the version number and copyrights.

.. option:: -save-temps
   
   Save intermediate files to current directory. Where possible, files are 
   named based on the source file. The generated file :file:`platform.h` is 
   always written with the same name, and therefore parallel builds with this 
   option enabled should be avoided.

   This option is not forwarded to xmap; see :option:`-Xmapper` if this is the 
   desired behaviour.

.. _xcc_manual_warning_options:

Warning Options
^^^^^^^^^^^^^^^

Many specific warnings can be controlled with options beginning
``-W``. Each of the following options has a negative form beginning
``-Wno-`` to turn off warnings.

.. option:: -fsyntax-only

   Checks the code for syntax errors only, then exits.

.. option:: -w

   Turns off all warning messages.

.. option:: -Wbidirectional-buffered-port

   Warns about the use of buffered ports not qualified with either ``in`` or ``out``. 
   This warning is enabled by default.

.. option:: -Wchar-subscripts

   Warns if an array subscript has type char.

.. option:: -Wcomment

   Warns if a comment-start sequence ``/*`` appears in a ``/*``
   comment, or if a backslash-newline appears in a ``//`` comment.
   This is default.

.. option:: -Wimplicit-int

   Warns if a declaration does not specify a type. In C also warns
   about function declarations with no return type.

.. option:: -Wmain

   Warns if the type of ``main`` is not a function with external linkage
   returning ``int``. In XC also warns if main does not take zero
   arguments. In C also warns if ``main`` does not take either zero or
   two arguments of appropriate type.

.. option:: -Wmissing-braces
   
   Warns if an aggregate or union initializer is not fully bracketed.

.. option:: -Wparentheses
   
   Warns if parentheses are omitted when there is an assignment in a
   context where a truth value is expected or if operators are nested
   whose precedence people often find confusing.

.. option:: -Wreturn-type
   
   Warns if a function is defined with a return type that defaults to
   ``int`` or if a return statement returns no value in a function
   whose return type is not ``void``.

.. option:: -Wswitch-default
   
   Warns if a ``switch`` statement does not have a ``default`` case.

.. option:: -Wswitch-fallthrough
   
   (XC only) Warns if a case in a ``switch`` statement with at least one
   statement can have control fall through to the following case.

.. option:: -Wtiming

   Warns if timing constraints are not satisfied. This is default.

.. option:: -Wtiming-syntax
   
   Warns about invalid syntax in timing scripts. This is default.

.. option:: -Wunused-function

   Warns if a static function is declared but not defined or a
   non-inline static function is unused.

.. option:: -Wunused-parameter

   Warns if a function parameter is unused except for its
   declaration.

.. option:: -Wunused-variable

   Warns if a local variable or non-constant static variable is unused
   except for its declaration.

.. option:: -Wunused
   
   Same as :option:`-Wunused-function`, :option:`-Wunused-variable` and
   ``-Wno-unused-parameter``.

.. option:: -Wall
   
   Turns on all of the above ``-W`` options.

The following ``-W...`` options are not implied by :option:`-Wall`.

.. option:: -Wextra, -W
   
   Prints extra warning messages for the following:

   -  A function can return either with or without a value (C, C++
      only).
   -  An expression statement or left-hand side of a comma expression
      contains no side effects. This warning can be suppressed by casting
      the unused expression to ``void`` (C, C++ only).
   -  An unsigned value is compared against zero with ``<`` or ``<=``.
   -  Storage-class specifiers like ``static`` are not the first
      things in a declaration (C, C++ only).
   -  A comparison such as ``x<=y<=z`` appears (XC only).
   -  The return type of a function has a redundant qualifier such as
      ``const``.
   -  Warns about unused arguments if ``-Wall`` or ``-Wunused`` is
      also specified.
   -  A comparison between signed and unsigned values could produce an
      incorrect result when the signed value is converted to unsigned.
      (Not warned if ``-Wno-sign-compare`` is also specified.)
   -  An aggregate has an initializer that does not initialize all
      members.
   -  An initialized field without side effects is overridden when
      using designated initializers (C, C++ only).
   -  A function parameter is declared without a type specifier in
      K&R-style functions (C, C++ only).
   -  An empty body occurs in an ``if`` or ``else`` statement (C, C++
      only).
   -  A pointer is compared against integer zero with ``<``, ``<=``,
      ``>``, or ``>=``. (C, C++ only).
   -  An enumerator and a non-enumerator both appear in a conditional
      expression. (C++ only).
   -  A non-static reference or non-static const enumerator and a
      non-enumerator both appear in a conditional expression (C++ only).
   -  Ambiguous virtual bases (C++ only).
   -  Subscripting an array which has been declared ``register`` (C++
      only).
   -  Taking the address of a variable which has been declared
      ``register`` (C++ only).
   -  A base class is not initialized in a derived class' copy
      constructor (C++ only).

.. option:: -Wconversion
   
   Warns if a negative integer constant expression is implicitly
   converted to an unsigned type.

.. option:: -Wdiv-by-zero
   
   Warns about compile-time integer division by zero. This is
   default.

.. option:: -Wfloat-equal
   
   Warns if floating point values are used in equality comparisons.

.. option:: -Wlarger-than-<len>
   
   Warns if an object of larger than `len` bytes is defined.

.. option:: -Wpadded

   Warns if a structure contains padding. (It may be possible to
   rearrange the fields of the structure to reduce padding and thus
   make the structure smaller.)

.. option:: -Wreinterpret-alignment

   Warns when a reinterpret cast moves to a larger alignment.

.. option:: -Wshadow

   Warns if a local variable shadows another local variable, parameter
   or global variable or if a built-in function is shadowed.

.. option:: -Wsign-compare

   Warns if a comparison between signed and unsigned values could
   produce an incorrect result when the signed value is converted to
   unsigned.

.. option:: -Wsystem-headers

   Prints warning messages for constructs found in system header
   files. This is not default. See :ref:`xcc_manual_directory_options`.

.. option:: -Wundef

   Warns if an undefined macro is used in a ``#if`` directive.

.. option:: -Werror

   Treat all warnings as errors.

.. option:: -Werror=<option>
   
   Turns a warning message into an error. The option should be one of
   the warning options to the compiler that can be prefixed with
   ``-W``.

   By default, the flag ``-Werror=timing-syntax`` is set. Turning this
   warning into an error implies that timing warnings (``-Wtiming``)
   are also errors and vice versa.

.. _xcc_manual_debugging_options:

Debugging Options
^^^^^^^^^^^^^^^^^

.. option:: -g

   Produces debugging information.

.. option:: -fresource-checks
   
   Produces code in the executable that traps if a resource allocation
   fails. This causes resource errors to be detected as early as
   possible.

.. option:: -fverbose-asm
   
   Produces extra compilation information as comments in intermediate
   assembly files.

.. option:: -dumpmachine
   
   Prints the target machine and exit.

.. option:: -dumpversion
   
   Prints the compiler version and exit.

.. option:: -print-multi-lib

   Prints the mapping from multilib directory names to compiler
   switches that enable them. The directory name is seperated from the
   switches by '``;``', and each switch starts with a '``@``' instead
   of the '``-``', without spaces between multiple switches.

.. option:: -print-targets
   
   Lists the target platforms (XN files) found via :envvar:`XCC_TARGET_PATH`, 
   excluding those in folders with name :file:`.deprecated`.

.. option:: -print-boards

   Same as :option:`-print-targets`, but only lists target platforms with the <
   Type> element set to "Board".

.. _xcc_manual_optimization_options:

Optimization Options
^^^^^^^^^^^^^^^^^^^^

Turning on optimization makes the compiler attempt to improve
performance and/or code size at the expense of compilation time and
the ability to debug the program.

.. option:: -O0
   
   Do not optimize. This is the default.

.. option:: -O, -O1
   
   Optimize. Attempts to reduce execution time and code size without
   performing any optimizations that take a large amount of
   compilation time.

.. option:: -O2

   Optimize more. None of these optimizations involve a space-speed
   tradeoff.

.. option:: -O3

   Optimize even more. These optimizations may involve a space-speed
   tradeoff; high performance is preferred to small code size.

.. option:: -Os
   
   Optimize for the smallest code size possible.

.. option:: -fschedule
   
   Attempt to reorder instructions to increase performance. This is
   not default at any optimization level.

.. option:: -funroll-loops

   Unroll loops with small iteration counts. 
   This is enabled at -O2 and above.

.. option:: -finline-functions

   Integrate simple functions into their callers. 
   This is enabled at -O2 and above and also at -Os.

Preprocessor Options
^^^^^^^^^^^^^^^^^^^^

The following options control the preprocessor.

.. option:: -E
   
   Preprocesses only, then exit.

.. option:: -D <name>
   
   Predefines `name` as a macro with definition 1.

.. option:: -D <name=definition>
   
   Tokenizes and preprocesses the contents of `definition` as if it
   appeared in a ``#define`` directive.

.. option:: -U <name>

   Removes any previous definition of `name`.

   :option:`-D` and :option:`-U` options are processed in the order given on the
   command line.

.. option:: -MD

   Outputs to a file a rule suitable for :command:`make` describing the
   dependencies of the source file. The default name of the dependency
   file is determined based on whether the :option:`-o` option is specified.
   If :option:`-o` is specified, the filename is the basename of the
   argument to :option:`-o` with the suffix ``.d``. If :option:`-o` is not
   specified, the filename is the basename of the input file with the
   suffix ``.d``. The name of the file may be overriden with :option:`-MF`.

.. option:: -MMD
   
   The same as :option:`-MD` expect that dependencies on system headers are
   ignored.

.. option:: -MF <file>
   
   Write dependency information to :file:`file`.

.. option:: -MP

   Emits phony targets for each dependency of the source file. Each
   phony target depends on nothing. These dummy rules work around
   errors ``make`` gives if header files are removed without updating
   the ``Makefile`` to match.

.. option:: -MT <file>

   Specifies the target of the rule emitted by dependency
   generation.

Mapper Options
^^^^^^^^^^^^^^

The following options control the mapper and its linker.

.. option:: -l <library>

   Searches the library library when linking. The linker searches and
   processes libraries and object files in the order specified. The
   actual library name searched for is :file:`lib{library}.a`.

   The directories searched include any specified with :option:`-L`.

   Libraries are archive files whose members are object files. The
   linker scans the archive for its members which define symbols that
   have so far been referenced but not defined.

.. option:: -nostartfiles

   Do not link with the system startup files.

.. option:: -nodefaultlibs

   Do not link with the system libraries.

.. option:: -nostdlib
  
   Do not link with the system startup files or system libraries.

.. option:: -s
  
   Removes all symbol table and relocation information from the
   executable.

.. option:: -default-clkblk <clk>

   Use `clk` as the default clock block. The clock block may be
   specified by its name in ``<xs1.h>`` or by its resource
   number.

   The startup code turns on the default clock block, configures it to
   be clocked off the reference clock with no divide and puts it into
   a running state. Ports declared in XC are initially attached to the
   default clock block. If this option is unspecified, the default
   clock block is set to ``XS1_CLKBLK_REF``.

.. option:: -Wm,<option>
  
   Passes `option` as an option to the linker/mapper. If `option`
   contains commas, it is split into multiple options at the commas.

   To view the full set of advanced mapper options, type
   :command:`xmap --help`.

.. option:: -Xmapper <option>
  
   Passes `option` as an option to the linker/mapper. To pass an option
   that takes an argument use :option:`-Xmapper` twice.

.. option:: -report
  
   Prints a summary of resource usage.

.. _xcc_manual_directory_options:

Directory Options
^^^^^^^^^^^^^^^^^

The following options specify directories to search for header
files and libraries.

.. option:: -I <dir>
  
   Adds :file:`dir` to the list of directories to be searched for header
   files.

.. option:: -isystem <dir>

   Searches :file:`dir` for header files after all directories specified by
   :option:`-I`. Marks it as a system directory.

   The compiler suppresses warnings for header files in system
   directories.

.. option:: -iquote <dir>
 
   Searches :file:`dir` only for header files requested with
   ``#include "file"`` (not with ``#include <file>``)
   before all directories specified by :option:`-I` and before the system
   directories.

.. option:: -L <dir>

   Adds :file:`dir` to the list of directories to be searched for by
   :option:`-l`.

.. _xcc_manual_environment_variables:

Environment
-----------

The following environment variables affect the operation of XCC.
Multiple paths are separated by an OS-specific path separator
('``;``' for Windows, '``:``' for Mac and Linux).

.. envvar:: XCC_INCLUDE_PATH
  
   A list of directories to be searched as if specified with ``-I``,
   but after any paths given with ``-I`` options on the command line.

.. envvar:: XCC_XC_INCLUDE_PATH
.. envvar:: XCC_C_INCLUDE_PATH
.. envvar:: XCC_CPLUS_INCLUDE_PATH
.. envvar:: XCC_ASSEMBLER_INCLUDE_PATH
  
   Each of these environment variables applies only when preprocessing
   files of the named language. The variables specify lists of
   directories to be searched as if specified with ``-isystem``, but
   after any paths given with ``-isystem`` options on the command
   line.

.. envvar:: XCC_LIBRARY_PATH
  
   A list of directories to be searched as if specified with ``-L``,
   but after any paths given with ``-L`` on the command line.

.. envvar:: XCC_DEVICE_PATH
  
   A list of directories to be searched for device configuration
   files.

.. envvar:: XCC_TARGET_PATH
  
   A list of directories to be searched for target configuration
   files. See :option:`-target`, :option:`-print-targets` and
   :option:`-print-boards`.

.. envvar:: XCC_EXEC_PREFIX
  
   If set, subprograms executed by the compiler are prefixed with the
   value of this environment variable. No directory seperater is added
   when the prefix is combined with the name of a subprogram. The
   prefix is not applied when executing the assembler or the mapper.

.. envvar:: XCC_DEFAULT_TARGET
  
   The default target platform, to be located as if specified with
   :option:`-target`. The default target platform is used if no target is
   specified with :option:`-target` and no XN file is provided as an input 
   file.