=================
Compiling Station
=================

There are two ways to compile Station for a specific hardware platform: (1) Compile directly on the target platform, or (2) Cross-compile for the target platform.  Compiling on the target platform is only possible if sufficient resources are available on the platform like, for example, on a Raspberry Pi.  For other embedded gateways with limited resources (e.g., Kerlink), cross-compiling is the only viable way.


Repository Structure
--------------------

The Station repository has the following directory structure:

- ``build-$platform-$variant``: Generated directory for resulting binaries;
- ``deps``: Required libraries;
- ``examples``: Examples for station usage;
- ``pysys``: Shared python scripts for simulation and testing;
- ``src``: Core source files;
- ``src-$platform``: Platform-specific source files.

.. - ``doc``: Documentation files;
.. - ``platform``: Platform-specific files and scripts;
.. - ``regr-tests``: Regression tests;
.. - ``utils``: Additional utilities.


Make Environment
----------------

For creating a binary executable, the ``make`` utility is used.  The following files are relevant for the make environment.

- ``makefile``: The core rules for building the executable;
- ``makefile.s2core``: Makefile rules for the core of the Station;
- ``setup.gmk``: Main setup file for the make environment, which controls the configuration for different platforms;
- ``setup-$platform.gmk``: Optional platform-specific rules and environment settings.

Typically, the platform and its corresponding variant are specified as parameters for a make target. Based on these parameters, the build environment is setup according to the rules specified in ``setup.gmk`` or ``setup-$platform.gmk``.

The following core make targets are available:

- ``deps``: To build the required dependencies;
- ``s-all``: To build the Station binary together with all required object files;
- ``s-clean``: To clean the object files and binaries related to the Station;
- ``clean``: To clean all Station objects and dependencies;
- ``super-clean``: To clean also all git repositories for the dependencies.


Dependencies
------------

Station has the following third party library dependencies:

- ``mbed TLS`` == 2.6;
- ``libloragw`` == 5.01.

Building Station from source, requires

- ``gcc`` >= 4.8.1 with support for `C11 with GNU extensions`;
- ``GNU make``
- ``bash``

In addition, ``git`` is used for source-code versioning and control.

Depending on the target platform, specific implementations of the ``libloragw`` library or additional libraries may be required.  Dependencies are downloaded from online repositories during the build process, typically using ``git``, and patched as required.


Preparing libloragw
-------------------

Patching
^^^^^^^^

By default, the ``libloragw`` library is downloaded from an online repository depending on the specific platform.  If the target platform requires modifications to the standard ``libloragw`` library, these can be added as a patch (e.g., ``deps/lgw/patch-$platform.patch``).


Different Library
^^^^^^^^^^^^^^^^^

If the target platform requires a different ``libloragw`` library, this dependency also can be configured in the ``setup.gmk`` makefile configuration file.

The build environment requires a makefile which places the resulting ``libloragw`` archive and corresponding include files in the ``build-platform-variant/lib`` and ``build-platform-variant/include`` directories.  Such an example makefile is the following:

.. code-block:: make

   TD=../..
   include ${TD}/setup.gmk

   TEKUI_LIB=${TD}/${BD}/lib/libtekui.a
   TEKUI_INC=${TD}/${BD}/include/tekui

   TEKUI_VERSION=3.5.6

   ARTEFACTS = ${TEKUI_LIB} ${TEKUI_INC}

   all: prepare ${ARTEFACTS}

   prepare:
	@mkdir -p ${TD}/${BD}/include ${TD}/${BD}/lib

   ${TEKUI_LIB} : ${TEKUI_VERSION}/libsx1301ar/libsx1301ar.a
	cp $< $@

   ${TEKUI_INC} : ${TEKUI_VERSION}/libsx1301ar/api_inc
	cp -r $< $@-temp
	rm -rf $@
	mv $@-temp $@

   clean super-clean:
	rm -rf ${ARTEFACTS}

   .PHONY: prepare all clean super-clean


Compiling on Target
-------------------

Compiling on the target platform requires installing a ``gcc`` compiler together with the ``make`` build tools on the target platform.

For example, to compile Station on a Raspberry-Pi Linux system, the following commands MAY be used:

.. code-block:: shell

  cd $STATION_REPO
  make platform=rpi variant=std


For example, to compile the required dependencies and a clean re-compile of Station on a Raspberry-Pi Linux system, the following commands MAY be used:

.. code-block:: shell

  cd $STATION_REPO
  make platform=linux variant=std deps s-clean s-all


See the ``setup.gmk`` makefile for a list of supported platforms and their respective configurations.


Cross-Compiling for Target
--------------------------

For cross-compilation for a specific target platform, a matching cross-compiler toolchain is required.  The make rules will select the toolchain based on the ``PLATFORM``.  The toolchain therefore MUST be installed in the ``$HOME`` directory of the user following the naming convention ``toolchain-platform``.

For example, to cross-compile for a Kerlink gateway, the following commands MAY be used:

.. code-block:: shell

  cd $STATION_REPO
  make platform=kerlink variant=std

**Note:** For Kerlink the ``toolchain_x86_64_v3.3`` is REQUIRED.


Adding a New Platform
---------------------

To add a new target platform with *newcool* as platform identifier, the following entries must be added to the ``setup.gmk`` file.  In most cases, these entries are very similar to existing platforms, which MAY be used for inspiration:

- ``ARCH.newcool``: Specifies the cross-compiler prefix;
- ``CFG.newcool``: Defines the underlying operating system, the radio abstraction layer for the ``libloragw`` library, and other configuration such as LEDS and so on;
- ``DEPS.newcool``: Specifies the library dependencies.  At a minimum these are the ``libloragw`` library (with potentially special variants) and ``mbed TLS``;
- ``CFLAGS.newcool``: Here special compiler flags can be set, if required;
- ``LIBS.newcool``: Define shared libraries to link against.

To compile for the new target platform simply, the following commands MAY be used:

.. code-block:: shell

  cd $STATION_REPO
  make platform=newcool variant=std