/ 
Build-Hopen-0.000007-TRIAL
River stage zero No dependents
/ Build::Hopen::Conventions

NAME

Build::Hopen::Conventions - conventions for using hopen(1) as a build system

SYNOPSIS

Build::Hopen is a flexible dataflow processor and task runner. However, its main use case is as a build system (e.g., a Makefile generator). To keep the core of hopen as flexible as possible, hopen(1) (build-system use cases) requires its components to follow the conventions described in this document.

These conventions are generally implemented/enforced in Build::Hopen::App and Build::Hopen::AppUtil.

Note: everything in this document is subject to change since Build::Hopen is currently under active development.

COMPONENTS USED BY THE BUILD SYSTEM

Project directory

Where the main hopen file file of the project is (see "HOPEN FILES").

Destination directory

Where the output will go. hopen(1) does not support in-source builds. The default directory is <project dir>/built.

Generator

A subclass of Build::Hopen::Gen that creates the build-system files. The generator's job is to arrange for coordinating work that needs to be done.

Toolset

A collection of operations (Build::Hopen::G::Op subclasses) that know how to process specific types of files. Toolsets are responsible for defining the work that the generator will coordinate.

Toolsets are technically independent of which generator is in use. However, a command-line toolset probably won't work with an XML-based generator! If no toolset is specified, the generator picks the default.

An architecture (optional)

An arbitrary string understood by the toolset or generator. Used, e.g., to select x86 vs. x64.

"Blueprint" files

These are the outputs of hopen. They are the inputs to make(1), ninja(1), or some other software-build tool.

HOPEN FILES

hopen configures a project by running one or more files matching .hopen.pl or *.hopen.pl. As the extension suggests, these are Perl source files.

The filename MY.hopen.pl is reserved. It is created by hopen in each destination directory to record the state of the build in that directory.

Hopen itself does not (knowingly) use any source filters, text replacement, pluggable keywords, or other fancy features. Everything in a hopen file is straight Perl.

Which hopen files are used

On any hopen(1) run, up to three hopen files are automatically located and executed. (Any of those can run any number of additional hopen files.) None of the three files has to exist. The three files are, in order of execution:

  • Build-state file

    The MY.hopen.pl in the destination directory. This sets the current phase (see "PHASES") and loads the data output by the last hopen(1) run.

    After MY.hopen.pl runs, the generator and toolset are loaded.

  • Project file

    The last-sorting .hopen.pl or *.hopen.pl file in the project directory. You can name your project file whatever you want --- only the extension has to match. That way you can call your build file .hopen.pl if you want it hidden, or z.hopen.pl if you want it to sort below all your other files. Sort order is Perl's default, which is by byte value.

  • Context file

    Sometimes you need to tweak the build of someone else's project to make it fit your environment. I run into this all the time on Cygwin. Therefore, hopen will look for a hopen file in the project's parent directory. That file is referred to as a "context file". Since the context file runs after the project file, the context file can change the way the project will be built.

    The filename of the context file is directory_name.hopen.pl for a project in directory_name. It doesn't matter what the project calls itself; the context file is found solely based on the directory name.

Note: if the project file or the context file has a newer modification time than the build-state file, the build-state file will not be loaded.

After those files are executed, any code provided by a -e command-line option is executed as if it were its own hopen file on disk, and any hopen file referenced by a -f option is executed. -e and -f options are processed in the order given on the command line.

Execution environment of a hopen file

Each hopen file is the body of a subroutine that may return a hashref ({}). That hashref is provided as input to the build graph. Each hopen file's output hashref, if any, is appended to the input hashref (using Hash::Merge with retainment precedent). Therefore, to leave the input unchanged, return {}, not $_[0].

Elements of the hashref starting with __R are reserved. Please don't read or write those elements if you want hopen to work! :) Similarly, all variables starting with __R are reserved.

The hopen file is executed in scalar context.

Each hopen file runs in an environment with everything from the following packages loaded (via Build::Hopen::HopenFileKit):

Variables usable in hopen files

These are defined in Build::Hopen.

$Generator

The current Build::Hopen::Gen instance.

$Toolset

The name of the current Build::Hopen::T::<stem> package root.

$Build

The Build::Hopen::G::DAG instance representing the current build. Goals in $Build will become, e.g., top-level targets of a generated Makefile.

$Phase

The current phase (read-only). Only MY.hopen.pl is allowed to change the phase (and not even that if --phase is specified on the hopen command line).

PHASES

hopen is a multi-phase build system. Unlike cmake(1), hopen runs deterministically in multiple steps. That way you don't have to run the build generator over and over again until it converges. (Yes, I have had this problem with cmake.) Each time you run hopen(1), it will run the next phase (saved in MY.hopen.pl). Currently, the phases are as follows, in order.

Check

During this phase, the generator, toolset, or hopen file can collect information about the environment.

Gen

During this phase, blueprint files and any supporting files (e.g., a config.h) are written to the destination directory.

After all the phases are run

Once all of hopen's phases have been run, you can run make(1), ninja(1), or whatever build system corresponds with the generator you have selected. You can do this by running hopen --build, if you wish.

INTERNALS

The build graph

Each operation (Build::Hopen::G::Op subclass) returns, or adds to the beginning of, a work arrayref. For example:

{
    work => [
        { from => ['hello.c'], to => ['hello.o'],
            how => ['gcc -c #first -o #out'] },
        { from => ['hello.o'], to => ['hello'],
            how => ['gcc #first -o #out'] }
    ]
}