Golem

Introduction

The starting point for any Golem project is the project file.

Golem currently supports 2 formats: golemfile.py and golemfile.json. Only one of them has to be created in the root directory of the project. If both are found, only golemfile.py is taken into account.

Here are equivalent examples illustrating their structure:

golemfile.py
def configure(project):
    project.dependency(name='json',
                       repository='https://github.com/nlohmann/json.git',
                       version='^3.0.0',
                       shallow=True)

    project.library(name='mylib',
                    includes=['mylib/include'],
                    source=['mylib/src'],
                    defines=['FOO_API_EXPORT'])

    project.export(name='mylib',
                   includes=['mylib/include'],
                   defines=['FOO_API_IMPORT'])

    project.program(name='hello-minimal',
                    source=['src'],
                    use=['mylib'],
                    deps=['json'])

The Python version declares a configure function with a project parameter. This project holds the definitions for programs, libraries, exports, dependencies and packages.

golemfile.json
{
    "dependencies": [
        {
            "name": "json",
            "repository": "https://github.com/nlohmann/json.git",
            "version": "^3.0.0",
            "shallow": true
        }
    ],
    "targets": [
        {
            "name": "mylib",
            "type": "library",
            "includes": ["mylib/include"],
            "source": ["mylib/src"],
            "defines": ["FOO_API_EXPORT"]
        },
        {
            "name": "hello",
            "type": "program",
            "source": ["src"],
            "use": ["mylib"],
            "deps": ["json"]
        }
    ],
    "exports": [
        {
            "name": "mylib",
            "includes": ["mylib/include"],
            "defines": ["FOO_API_IMPORT"]
        }
    ]
}

The JSON version declares the same definitions but in multiple arrays for better readability.

  • dependencies contains all the dependency definitions.
  • targets contains all the program and library definitions of the project.
  • exports contains all the export definitions of the project, internally used by the project or meant to be used by other projects.
  • packages contains all the package definitions of the project.

All the definitions, except for the package definition, support a common set of parameters. That is, program, library, export and dependency definitions all hold a common configuration set, to define target names, compiler flags, linking flags, sources, headers, etc.

Also, to conditionally apply parameters on a configuration, Golem provides a simple and yet powerful condition mechanism.

Examples

To learn with examples have a look at:

Prev
Getting Started
Next
Configurations