How to use arguments and return codes
=====================================

Arguments and return codes are not really useful in a true embedded 
application, since a user is not present to provide them or react to them. 
However, they are particularly useful during unit and regression testing, as 
they allow tests to be configured and pass/fail results returned simply.

.. note::

   The facility to use arguments and return codes is only available for a 
   single tile application; an application with a main() function written in 
   the C language.

   It makes no sense for a multi-tile application (with an XC main() function) 
   to use arguments and return codes, because there is no mechanism to define 
   which is the 'master' tile, nor define how it should distribute the 
   arguments and collate the return code. Therefore this tutorial is suited 
   only to single tile testing.

To add command line arguments, create a main() function with the usual 
prototype:

.. literalinclude:: examples/args-and-ret-codes/main.c
   :caption: main.c

Build with a non-zero value for :option:`xcc -fcmdline-buffer-bytes`:

.. code-block:: bash

    $ xcc main.c -target=XCORE-200-EXPLORER -fcmdline-buffer-bytes=1024

.. note::

    If you forget to the -fcmdline-buffer-bytes parameter, then a buffer of 
    size zero will be allocated, and argc will always hold a value of zero. No 
    error or warning will be raised. So don't forget!

Run with using :option:`xrun --args`, and examine the return code:

.. code-block:: bash

    $ xrun --io --args a.xe giraffe elephant
    Arg 0 a.xe
    Arg 1 giraffe
    Arg 2 elephant
    $ echo $?
    3

Similar behaviour can be found using :option:`xsim --args` and
:option:`xgdb --args`.