Getting_started

Introduction to pgen yaml files

Let's assume you have a project and want to generate projects.

Step 1 Firstly, there is the main record file, which is called by default projects.yaml. It can be placed anywhere, although it is wise to place it in the root directory, to be visible.

This is how the directory tree for project generator can look like:

+---project
    +---folders
    +---records
    +---projects.yaml

There is the folder records. What does it include? There should be defined records for projects.

What is it, a record?

Record is YAML file which describes a project as a list of modules. There should be a file with a project/all projects. Each project has own record, to describe requirements for the project. The project consists of modules. A module is a list of files, which share the same attributes.

Projects yaml file It defines all projects available for repository. It can consist of one or more projects. Each project includes other records - one project definition file and many modules. It can define also enviroment settings as paths for builders, for example gcc arm path or any other tool. The enviroments settings are set to default values which might not match your settings.

This is an example of the main record:

projects:
  my_first_project: #name of the project
  - main.yaml   # list of yaml files it includes

settings:
  tools:
    iar:
      path:
      - path to iar
      template:
      - project.ewp #template project to be used for all projects

It defines the projects available in a repository, and provides additional settings, like setting path to tools (iar above) and setttings valid for all projects (they can be specified per project, in most cases they are the same per repository).

Project definition file This is a unique record file. It defines specific attributes for specified project.

A module file This is a file which defines a module. A module is bunch of files with common attributes. For instance, if there are target specific files, we can create a new module named target_specific.yaml file and define all attributes specific for that module.

Once you set up records (list of projects, project file and modules), start using export script to generate projects.

Important note, all paths in records require to be defined with a full path (from the root directory).

Create the main record file (projects.yaml)

As a first step, create a record of projects list file.

projects:
  kl25z_blinky:
  - records/kl25z_cmsis.yaml
  - records/kl25z_target.yaml
  - records/kl25z_blinky.yaml

There is one project defined, named kl25z_blinky. It consists of 3 records.

How does kl25z_blinky projects list file look like?

common:
  output:
  - exe #this is default ,you can ommit this, can be lib
  target:
  - frdm-kl25z
  includes:
  - examples/blinky
  sources:
  - examples/blinky/main.cpp
  macros:
  - ALLOWED_GENERIC_TICKER

tool_specific:
  uvision:
    macros:
    - MY_NICE_MACRO_VALID_ONLY_FOR_UVISION
  gcc_arm:
  misc:
    libraries:
    - m
    - nosys
    optimization:
    - O1
    compiler_options:
    - g
    - ggdb
    - Wall

The KL25Z blinky project is defined for uVision and GCC ARM. There are common attributes (generic) and tool specific. Each ide has own attributes, which are parsed by specific ide parser class. The common attributes are parsed by yaml parser class. The other 2 yaml records file (cmsis, target) follow the same syntax, they define linker file, core files and target specific files as a driver for kl25z for example. Once we have records defined, we should be able to generate a project.

You can list sources or directories which gets then expanded to all sources within that directory. If a record does not define any include path, they get derived from source directories (source directories are taken from sources automatically).

How to generate a project

**pgen should be run from the project's root **

For instance, to generate all projects within projects.yaml file for IAR ARM, run it as follows:

pgen export -f projects.yaml -t iar_arm

To enable debug messages, use -v after pgen , for example pgen -v -v -v export, which should raise logging level to debug.

The projects are genereted by default in the root directory, under the generated_projects. Once project/projects generated, they can be built. Use argument -b to build them. This feature is usefull for automated testing for example.

To redirect the export output, define project_dir in the project:

common:
  export_dir:
  - example/blinky
tool_specific:
  uvision:
  export_dir:
  - uvision

Or for all projects, use in the projects.yaml file

settings:
  export_dir:
  - output/{tool}/{project_name}

{tool}, {project_name} and {target} are keywords available for output dir, so a user can change the behaviour depending on a project. Without defining export_dir, pgen exports to generated_projects/{tool}_{project_name}.

The code above redirects the export to example/blinky/uvision for uvision tool. The name can be also set in the common area.

Sharing is caring - If you find an issue, any limitation, or possible improvements, please report it on github. Any feedback is appreciated !