Getting_started

Introduction to progen 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 iar projects

It defines the projects available in a repository, and provides additional settings, like setting path to tools (iar above, this is used for building a project) 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:
      standard_libraries:
      - m
      - nosys
      common:
      - O1
      - -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

** progen 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:

progen generate -f projects.yaml -t iar_arm

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

The projects are generated by default in the root directory, under the generated_projects. Once project/projects are 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 export_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, progen 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.