The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Build-Hopen-0.000005-TRIAL
River stage zero No dependents
/ Build::Hopen

NAME

Build::Hopen - A build generator with first-class edges and explicit dependencies

SYNOPSIS

Input is the last-sorting file in . matching *.hopen, unless you specify otherwise. That way you can call your build file .hopen if you want it hidden, or z.hopen if you want it to sort below all your other files. Sort order is Lua's <, which is by byte value.

Output is a build file for a build system (Ninja or Make will be first). You will eventually be able to pick a generator, a la CMake. The invoker will put the selected generator's path first in @INC, but other than that it's all straight Perl.

INSTALLATION

Easiest: install cpanminus if you don't have it - see https://metacpan.org/pod/App::cpanminus#INSTALLATION. Then run cpanm Build::Hopen.

Manually: clone or untar into a working directory. Then, in that directory,

perl Makefile.PL
make
make test

... and if all the tests pass,

make install

If some of the tests fail, please check the issues and file a new one if no one else has reported the problem yet.

VARIABLES

Not exported by default, except as noted.

$VERBOSE

Set to truthy to get debug output on stderr from hopen's internals.

$E

$E holds the current Build::Hopen::Environment, if any. Exported by default.

FUNCTIONS

All are exported by default unless indicated.

boolify

Convert a scalar to a Boolean as Perl does, except:

  • Falsy

    /^(false|off|no)$/i

  • Truthy

    "0"

So false, off, no, empty string, undef, and numeric 0 are falsy, and all other values (including string '0') are truthy.

hnew

Creates a new Build::Hopen instance. For example:

hnew DAG => 'foo';

is the same as

Build::Hopen::G::DAG->new( name => 'foo' );

If the provided name does not include a double-colon, it is first tried after Build::Hopen::G::. It is then tried in Build::Hopen:: and as a complete package name. The first one that succeeds is used.

The first parameter must be a part of a class name, and the second parameter must be the name of the new instance. All other parameters are passed unchanged to the relevant constructor.

hlog

Log information if "$VERBOSE" is set. Usage:

hlog { <list of things to log> };

The items in the list are joined by ' ' on output, and a '\n' is added. Each line is prefixed with '# ' for the benefit of test runs.

The list is in {} so that it won't be evaluated if logging is turned off. It is a full block, so you can run arbitrary code to decide what to log. If the block returns an empty list, hlog will not produce any output.

clone

Clones a scalar or a reference. Thin wrapper around "dclone" in Storable. Not exported by default.

setE

Set the current "$E". Usage:

my $saver = setE(<a reference to a Build::Hopen::Environment>)

The return value is from Sub::ScopeFinalizer. You must assign it to a lexical ($saver in the example above) to revert changes to "$E" when that lexical goes out of scope.

See https://stackoverflow.com/a/31864302/2877364 by ikegami for why you can't just use local $E=....

CONSTANTS

UNSPECIFIED

A Build::Hopen::Util::NameSet that matches any non-empty string. Always returns the same reference, so that it can be tested with ==.

NOTHING

A Build::Hopen::Util::NameSet that never matches. Always returns the same reference, so that it can be tested with ==.

INTERNALS

- C<Op>: A class representing an operation
  - C<Op:run()> takes a table of inputs and returns a table of outputs.
  - C<Op:describe()> returns a table listing those inputs and outputs.

Implementation

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.

SUPPORT

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

perldoc Build::Hopen
perldoc hopen

You can also look for information at:

INSPIRED BY

  • Luke

  • a bit of Ant

  • a tiny bit of Buck

  • my own frustrations working with CMake.

LICENSE AND COPYRIGHT

Copyright (C) 2018 Christopher White, <cxwembedded at gmail.com>

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