- COMPONENTS USED BY THE BUILD SYSTEM
- HOPEN FILES
App::hopen::Conventions - conventions for using hopen(1) as a build system
Data::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, App::hopen (build system) requires its components to follow the conventions described in this document.
Note: everything in this document is subject to change since
App::hopen is currently under active development.
- 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
A subclass of App::hopen::Gen that creates the build-system files. The generator's job is to arrange for coordinating work that needs to be done.
A collection of operations (App::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 configures a project by running one or more files matching
*.hopen.pl. As the extension suggests, these are Perl source files.
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.
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:
MY.hopen.plin the destination directory. This sets the current phase (see "PHASES") and loads the data output by the last hopen(1) run.
MY.hopen.plruns, the generator and toolset are loaded.
*.hopen.plfile 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.plif you want it hidden, or
z.hopen.plif you want it to sort below all your other files. Sort order is Perl's default, which is by byte value.
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.plfor 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.
-f options are processed in the order given on the command line.
The hopen files are run in order to build up a hashref that will be the input to the build graph. The hopen files, while they run, also populate the build graph.
Each hopen file is the body of a subroutine that receives a hashref from the last-run hopen file and may return a hashref (
undef. 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
Any return value that is not a hashref will be ignored.
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 App::hopen::HopenFileKit):
:hopenfilespecified, so you get, e.g., "on" in App::hopen::Phases.
These are defined in App::hopen::BuildSystemGlobals.
The current App::hopen::Gen instance.
The name of the current
The Data::Hopen::G::DAG instance representing the current build. Goals in
$Buildwill become, e.g., top-level targets of a generated
The current phase (read-only). Only
MY.hopen.plis allowed to change the phase (and not even that if
--phaseis specified on the hopen command line).
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.
During this phase, the generator, toolset, or hopen file can collect information about the environment.
During this phase, blueprint files and any supporting files (e.g., a
config.h) are written to the destination directory.
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.
The hopen files run, and generate a command graph. The command graph includes nodes that implement App::hopen::G::Cmd. The idea is that the hopen files specify the commands you would run to build your software by hand.
Each command node, when run, outputs a
madearrayref of App::hopen::Asset instances.
The command graph is run, with a generator made available to it. Command nodes provide asset nodes to the generator and to later command nodes. The asset nodes implement App::hopen::G::AssetNode. The specific subclass they implement is determined by the generator.
The generator runs the asset graph to output the blueprint files.