src/starboard/doc/building.md

# Building Starboard

Starboard currently uses GYP as the basis of its build system, though there is
already some movement towards GN as a replacement.

While you can integrate Starboard into any build system, there are enough knobs
and dials that it would be a daunting effort. Instead, Starboard tries to provide a
functional build framework that an application developer can easily integrate with.


## The Flow

The basic flow of how Starboard builds is:

1. `starboard/build/gyp` - Parse command line parameters and pass them into
   `GypRunner`.
2. `starboard/build/gyp_runner.py`
   1. Load the `PlatformConfiguration`.
   2. Load the `ApplicationConfiguration`.
   3. Calculate and merge the GYP includes, GYP variables, environment
      variables, and generator variables, and pass them into GYP.
3. tools/gyp - Parse all the .gyp and included .gypi files, generate ninja.
4. ninja - Build all the source files.


## The Platform vs. the Application

In this documentation, you will see a lot of discussion about things being
Platform or Application concerns.

The Platform is more-or-less what you think it is -- Everything you might need
to build any Starboard Application on a given platform.

It helps to think about an Application as a broader concept than a single
program. From Starboard's build system's perspective, an Application is a
*single configuration of build variables per platform*, which may produce many
build targets beyond a single executable - shared libraries, tests, and so on.


## Application Customization

Each Application will probably want to define its own knobs, dials, and defaults
to be able to be customized per platform, and so Starboard provides a space for
the Application to do that.

Each Application can provide a platform-specific ApplicationConfiguration
instance by creating a python module in
`<platform-directory>/<application-name>/configuration.py`. This module must
contain a class definition that extends from
`starboard.build.application_configuration.ApplicationConfiguration`. If the
class is not found in the platform-specific location, a generic configuration
will be loaded, as dictated by the `APPLICATIONS` registry in
`starboard_configuration.py`.

Additionally, the Application can provide a GYPI file to be included at
`<platform-directory>/<application-name>/configuration.gypi`. This will, by
default, be included at the end of all other configuration GYPI files, but this
behavior can be arbitrarily customized by the loaded `ApplicationConfiguration`
class.


## HOWTO: Create a new Application

1. Create your Application's root `.gyp` file. Often called `all.gyp` or
   something similar.

2. Create a cross-platform `ApplicationConfiguration` python class for your
   application. Take a look at
   [`cobalt_configuration.py`](../../cobalt/build/cobalt_configuration.py) as an
   example.

   Define a subclass of
   `starboard.build.application_configuration.ApplicationConfiguration` and
   override any desired methods. In particular, you probably at least want to
   override the `GetDefaultTargetBuildFile()` method to point at your root
   `.gyp` file from step 1.

3. Register your Application in your `starboard_configuration.py` file in your
   source tree root.

   To do this, just add an entry to the `APPLICATIONS` Mapping that maps your
   canonical Application name to the cross-platform `ApplicationConfiguration`
   subclass constructor for your application.

       APPLICATIONS = {
           # ...

           'example_app': example_app.ExampleAppConfiguration

           # ...
       }

At this point, you should be able to build your application with:

    starboard/build/gyp -a <application-name>