/ 
App-hopen-0.000013-TRIAL
River stage zero No dependents
/ App::hopen

NAME

App::hopen - Graph-driven cross-platform build system

CURRENT STATUS

Most features are not yet implemented ;) . However it will generate a Makefile or build.ninja file for a C Hello, World program at this point! It can generate command lines for gcc(1) or for Microsoft's cl.exe.

INTRODUCTION

hopen is a cross-platform software build generator. It makes files you can pass to Make, Ninja, Visual Studio, or other build tools, to compile and link your software. hopen gives you:

  • A full, Turing-complete, robust programming language to write your build scripts (specifically, Perl 5.14+)

  • No hidden magic! All your data is visible and accessible in a build graph (whence "graph-driven").

  • Context-sensitivity. Your users can tweak their own builds for their own platforms without affecting your project.

See App::hopen::Conventions for details of the input format.

Why Perl? Because (1) you probably already have it installed, and (2) it is the original write-once, run-everywhere language!

Example

Create a file .hopen.pl in your source tree. Then:

$ hopen
From ``.'' into ``built''
Running Check phase

Now built/MY.hopen.pl has been created, and loaded with information about your configuration. You can edit that file if you want to change what will happen next.

$ hopen
From ``.'' into ``built''
Running Gen phase

Now built/Makefile has been created.

$ hopen --build
Building in foo/built

And your software is ready to go! make has been run in built/, with output left in built/.

See App::hopen::Conventions for information on writing .hopen.pl files.

SYNOPSIS

hopen [options] [--] [destination dir [project dir]]

If no project directory is specified, the current directory is used.

If no destination directory is specified, <project dir>/built is used.

See App::hopen and App::hopen::Conventions for more details.

OPTIONS

-a architecture

Specify the architecture. This is an arbitrary string interpreted by the generator or toolset.

--build

Run the generator to process the blueprint files. Cannot be used with --fresh.

-e Perl code

Add the Perl code as if it were a hopen file. -e files are processed after all other hopen files, so can modify anything that has been set up by those files. Can be specified more than once.

--fresh

Start a fresh build --- ignore any MY.hopen.pl file that may exist in the destination directory. Cannot be used with --build.

--from project dir

Specify the project directory. Overrides a project directory given as a positional argument.

-g generator (or -G)

Specify the generator. The given generator should be either a full package name or the part after App::hopen::Gen::. Also accepts -G to ease the transition from cmake.

-t toolset (or -T)

Specify the toolset. The given toolset should be either a full package name or the part after App::hopen::T::. Also accepts -T to ease the transition from cmake.

--to destination dir

Specify the destination directory. Overrides a destination directory given as a positional argument.

--phase phase

Specify which phase of the process to run. Note that this overrides whatever is specified in any MY.hopen.pl file, so may cause unexpected results!

If --phase is given, no other hopen file can set the phase, and hopen will terminate if a file attempts to do so.

-q

Produce no output (quiet). Overrides -v.

-v, --verbose=n

Verbose. Specify more v's for more verbosity. At present, -vv (equivalently, --verbose=2) gives you detailed traces of the data, and -vvv gives you more detailed code tracebacks on error.

--version

Print the version of hopen and exit

INTERNALS

After the hopen file is processed, cycles are detected and reported as errors. *(TODO change this to support LaTeX multi-run files?)* Then the DAG is traversed, and each operation writes the necessary information to the file being generated.

INTERNAL DATA

$RUNNING

Set truthy when a hopen run is in progress. This is so modules don't have to die() if they are being run under perl -c, for example.

TODO replace this with a package parameter --- see "_language_import" in App::hopen::HopenFileKit.

$_hrData

The hashref of the current data we have built up by processing hopen files.

$_did_set_phase

Set to truthy if MY.hopen.pl sets the phase.

$_hf_pkg_idx

Used to give each hopen file or -e a unique package name.

%CMDLINE_OPTS

A hash from internal name to array reference of [getopt-name, getopt-options, optional default-value].

If default-value is a reference, it will be the destination for that value.

INTERNAL FUNCTIONS

_parse_command_line

Takes {into=>hash ref, from=>array ref}. Fills in the hash with the values from the command line, keyed by the keys in "%CMDLINE_OPTS".

_execute_hopen_file

Execute a single hopen file, but do not run the DAG. Usage:

_execute_hopen_file($filename[, options...])

This function takes input from "$_hrData" unless a DATA=>{...} option is given. This function updates "$_hrData" based on the results.

Options are:

phase

If given, force the phase to be the one specified.

quiet

If truthy, suppress extra output.

libs

If given, it must be an arrayref of directories. Each of those will be turned into a use lib statement (see lib) in the generated source.

_run_phase

Run a phase by executing the hopen files and running the DAG. Reads from and writes to "$_hrData", which must be initialized by the caller. Usage:

my $hrDagOutput = _run_phase(files=>[...][, options...])

Options phase, quiet, and libs are as "_execute_hopen_file". Other options are:

files

(Required) An arrayref of filenames to run

norun

(Optional) if truthy, do not run the DAG. Note that the DAG will also not be run if it is empty.

_inner

Do the work for one invocation of hopen(1). Dies on failure. Main() then translates the die() into a print and error return.

Takes a hash of options.

The return value of _inner is unspecified and ignored.

Main

Command-line runner. Call as App::hopen::Main(\@ARGV).

AUTHOR

Christopher White, cxwembedded at gmail.com

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::hopen                      For command-line options
perldoc App::hopen::Conventions         For terminology and workflow
perldoc Data::Hopen                     For the underlying engine

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (c) 2018--2019 Christopher White. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA