/ 
App-hopen-0.000010
River stage zero No dependents
/ App::hopen

NAME

App::hopen - hopen build system command-line interface

SYNOPSIS

(Note: most features are not yet implemented ;) . However it will generate a Makefile for a basic Hello, World program at this point!)

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.

  • 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!

USAGE

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::Conventions for more details.

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.

%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.

_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".

$_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.

_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.

The return value of _inner is unspecified and ignored.

Main

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

OPTIONS

-a architecture

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

-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.

--from project dir

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

-g generator

Specify the generator. The given generator should be either a full package name or the part after App::hopen::Gen::.

-t toolset

Specify the toolset. The given toolset should be either a full package name or the part after App::hopen::T::.

--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

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 internals

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