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 module_build_info files.

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_.

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.

The Application Makefile#

Every application directory should contain a file named 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.

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.

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.

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.

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.

XCC_FLAGS_<filename>#: Overrides the flags passed to xcc for the filename specified. This option overrides the flags for all build configurations.

VERBOSE#: If set to 1, enables verbose output from the make system.

SOURCE_DIRS#: Specifies the list of directories, relative to the application directory, that have their contents compiled. By default all directories are included.

INCLUDE_DIRS#: Specifies the directories to look for include files during the build. By default all directories are included.

LIB_DIRS#: Specifies the directories to look for libraries to link into the application during the build. By default all directories are included.

EXCLUDE_FILES#: Specifies a space-separated list of source file names (not including their path) that are not compiled into the application.

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:

USED_MODULES = module_xtcp module_ethernet

MODULE_LIBRARIES#: This option specifies a list of preferred libraries to use from modules that specify more than one. See Using XMOS Makefiles to create binary libraries for details.

The module_build_info file#

Each module directory should contain a file named 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.

DEPENDENT_MODULES#: Specifies the dependencies of the module. When an application includes a module it will also include all its dependencies.

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:

MODULE_XCC_FLAGS = $(XCC_FLAGS) -O3

MODULE_XCC_XC_FLAGS#: If set, these flags are passed to xcc instead of MODULE_XCC_FLAGS for all .xc files within the module.

MODULE_XCC_C_FLAGS#: If set, these flags are passed to xcc instead of MODULE_XCC_FLAGS for all .c files within the module.

MODULE_XCC_ASM_FLAGS#: If set, these flags are passed to xcc instead of MODULE_XCC_FLAGS for all .s or .S files within the module.

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.