.. _xmos_makefile_manual: Using the XCOMMON build system ============================== The **common XMOS Makefile** provides support for building applications and source code modules. You need only specify the required properties of the build in **Application Makefiles** and :file:`module_build_info` files. .. _xmos_makefile_manual_project_structure: Applications and Modules ------------------------ An application is made up of source code unique to the application and, optionally, source code from modules of common code or binary libraries. When developing an application, the working area is described in terms of *workspaces*, *applications* and *modules*. Workspace A *workspace* is a container for several projects. Applications An *application* is a project containing source files and a Makefile that builds into a single executable (``.xe``) file. By convention application directories start with the prefix ``app_``. Modules A *module* is a directory containing source files and/or binary libraries. The source does not build to anything by itself but can be used by applications. By convention module directories start with the prefix ``module_``. .. _xmos_makefile_manual_project_example: Workspace structure and automatic module detection .................................................. Depending on the configuration of your workspace the Makefiles will search folders on your file system to find modules used by an application. The simplest structure is shown below:: app_avb_demo1/ app_avb_demo2/ module_avb1/ module_avb2/ module_xtcp/ module_zeroconf/ module_ethernet/ In this case when building the applications, the build system will find the modules on the same directory level as the applications. Sometimes applications and modules are organized in separate repositories:: repo1/ app_avb_demo1/ module_avb1/ repo2/ module_zeroconf/ If the Makefiles detect that the folder containing the application is a repository then the Makefiles will search the sub-folders of all repositories at the same nesting level for modules (in this case the sub-folders of ``repo1`` and ``repo2``). The Makefiles will detect a folder as a repository if one of the following conditions hold: * The folder has a ``.git`` sub-folder. * The folder starts with the prefix ``sc_``, ``ap_``, ``sw_``, ``tool_`` or ``lib_``. * The folder contains a file called ``.xcommon_repo`` or ``xpd.xml``. If the folder above the application is detected as a repository but the folder above that is then the Makefiles will search at that level. So in the following case:: repo1/ examples/ app_avb_demo1/ module_avb1/ repo2/ module_zeroconf/ The sub-folders of ``repo1`` and ``repo2`` will be searched. In addition to the automatic searching for modules, the environment variable ``XMOS_MODULE_PATH`` can be set to a list of paths that the Makefiles should search. If you just want to solely use the user specified search path then the automatic searching for modules can be disabled by setting the environment variable ``XCOMMON_DISABLE_AUTO_MODULE_SEARCH`` to ``1``. .. _xmos_makefile_manual_app_makefile: The Application Makefile ------------------------ Every application directory should contain a file named :file:`Makefile` that includes the common XMOS Makefile. The common Makefile controls the build, by default including all source files within the application directory and its sub-directories. The application Makefile supports the following variable assignments. .. make-var:: XCC_FLAGS[_config] Specifies the flags passed to xcc during the build. This option sets the flags for the particular build configuration *config*. If no suffix is given, it sets the flags for the default build configuration. .. make-var:: XCC_C_FLAGS[_config] If set, these flags are passed to xcc instead of ``XCC_FLAGS`` for all ``.c`` files. This option sets the flags for the particular build configuration *config*. If no suffix is given, it sets the flags for the default build configuration. .. make-var:: XCC_ASM_FLAGS[_config] If set, these flags are passed to xcc instead of ``XCC_FLAGS`` for all ``.s`` or ``.S`` files. This option sets the flags for the particular build configuration *config*. If no suffix is given, it sets the flags for the default build configuration. .. make-var:: XCC_MAP_FLAGS[_config] If set, these flags are passed to xcc for the final link stage instead of ``XCC_FLAGS``. This option sets the flags for the particular build configuration *config*. If no suffix is given, it sets the flags for the default build configuration. .. make-var:: XCC_FLAGS_ Overrides the flags passed to xcc for the filename specified. This option overrides the flags for all build configurations. .. make-var:: VERBOSE If set to 1, enables verbose output from the make system. .. make-var:: SOURCE_DIRS Specifies the list of directories, relative to the application directory, that have their contents compiled. By default all directories are included. .. make-var:: INCLUDE_DIRS Specifies the directories to look for include files during the build. By default all directories are included. .. make-var:: LIB_DIRS Specifies the directories to look for libraries to link into the application during the build. By default all directories are included. .. make-var:: EXCLUDE_FILES Specifies a space-separated list of source file names (not including their path) that are not compiled into the application. .. make-var:: USED_MODULES Specifies a space-separated list of module directories that are compiled into the application. The module directories should always be given without their full path irrespective of which project they come from, for example: .. code-block:: makefile USED_MODULES = module_xtcp module_ethernet .. make-var:: MODULE_LIBRARIES This option specifies a list of preferred libraries to use from modules that specify more than one. See :ref:`makefile_libraries` for details. .. _xmos_makefile_manual_module_build_info: The module_build_info file -------------------------- Each module directory should contain a file named :file:`module_build_info`. This file informs an application how to build the files within the module if the application includes the module in its build. It can optionally contain several of the following variable assignments. .. make-var:: DEPENDENT_MODULES Specifies the dependencies of the module. When an application includes a module it will also include all its dependencies. .. make-var:: MODULE_XCC_FLAGS Specifies the options to pass to xcc when compiling source files from within the current module. The definition can reference the ``XCC_FLAGS`` variable from the application Makefile, for example: .. code-block:: makefile MODULE_XCC_FLAGS = $(XCC_FLAGS) -O3 .. make-var:: MODULE_XCC_XC_FLAGS If set, these flags are passed to xcc instead of :make-var:`MODULE_XCC_FLAGS` for all ``.xc`` files within the module. .. make-var:: MODULE_XCC_C_FLAGS If set, these flags are passed to xcc instead of :make-var:`MODULE_XCC_FLAGS` for all ``.c`` files within the module. .. make-var:: MODULE_XCC_ASM_FLAGS If set, these flags are passed to xcc instead of :make-var:`MODULE_XCC_FLAGS` for all ``.s`` or ``.S`` files within the module. .. make-var:: OPTIONAL_HEADERS Specifies a particular header file to be an optional configuration header. This header file does not exist in the module but is provided by the application using the module. The build system will pass the a special macro ``__filename_h_exists__`` to xcc if the application has provided this file. This allows the module to provide default configuration values if the file is not provided.