Skip to main content

How to use xcdl

This section is intended for those who plan to use xcdl in their own projects.

note

Work in progress.

The first step in understanding xcdl is learning how to use it in existing xcdl-enabled projects.

The subsequent steps, which involve adding xCDL metadata to existing projects, are presented in the Components Author's Guide page.

Use existing xcdl-enabled projects​

For projects that already include xCDL metadata, the basic xCDL workflow consists of these primary tasks:

  • create the xCDL configuration
  • generate the build tree
  • run the build
  • eventually run/debug the resulting artefact

The simplest way to experiment with this workflow is by using an existing project. For example, you can start with a basic C project that prints the traditional "Hello, World!" message.

The first step is to clone the demo project into a temporary folder of your choice:

git clone https://github.com/xpack/xcdl-demo-hello1.git
note

The demo project is not yet available.

Install dependencies​

A preliminary step in the workflow is to satisfy the project dependencies. In this example, xpm will install clang (since it is more portable than gcc).

cd xcdl-demo-hello1
xpm install

Check configuration​

The demo project already has the xCDL configuration.

You can inspect it with:

% xcdl config list --config demo
...

Create the build tree​

xpm run prepare

The above xpm action will run the xcdl setup command:

xcdl setup --configuration-name demo --build-folder build/demo --builder 'xcdl-make' --toolchain-file=clang.json

This will create the build tree in the build/demo folder.

Build the artefact​

The next action is to build the executable:

xpm run build

This will run the xcdl build command, which in turn will run make:

% xcdl build --build-folder build/demo
...

Run the program​

The final step is to execute the program:

% build/demo/hello1
Hello World!

TODO:

  • use a toolchain file to pass the clang definitions
  • add a more elaborate demo, with several components and options to be configured, and show how the configuration process looks like, both in VS Code and in a terminal.