FLENGMAKE(1)

💅 NAME

FLENGMAKE(1) is here, bestie, straight from the General Commands Manual — and it’s literally a build tool for programs written in FGHC, Strand, PCN or FLENG. 💖

✨ SYNOPSIS

flengmake [[MODE]] [OPTION] [ARGUMENT ...]

🌸 DESCRIPTION

okay so flengmake is the tool that builds projects made of programs and libraries implemented in one or more languages supported by the FLENG compiler. It assumes a certain convention of structuring code and builds executables automatically using the minimal number of build steps. Iconic behavior, no cap. ✨

MODE can be either "clean" to remove all build artifacts, "show" to generate a graph suitable for visualization via dot(1), or "build" (the default) to rebuild one or more parts of the project, if necessary.

OPTION should be one of the following:

• -h — Show usage information and exit. 🫶
• --version — Show FLENG system version and exit.
• -v — Be verbose, show explanations for the build steps taken.
• -n — Do not actually rebuild, just show the steps that would be taken.
• -r DIRECTORY — Specifies the root directory of the project. If this option is not given, the current working directory is assumed to be the root directory. Note that the actual working directory is not changed.
• -OPTION -VALUE — Set a project-wide build option to the value given. See below for more information about build options.

🦋 PRINCIPLE OF OPERATION

flengmake traverses the root directory and locates any source files with the extensions .ghc, .fghc, .strand, .st, .pcn, .kl1, .fl and .fleng, assuming these to be code written in one of the languages supported by the FLENG system. The code is then scanned and module-uses and uses of included files are analyzed to infer dependencies between the different modules and programs, resulting in an internal list of targets. 👑

flengmake knows the following types of targets:

• programs — Top-level programs that compile to an executable. A file is considered to represent a program if it has no "module" declaration and is not included in any other file in the project.
• modules — Separately compiled modules used in other programs, modules and libraries. A file is considered to represent a module if it has a "module" declaration and is not included in any other file in the project.
• libraries — A collection of modules linked into a static library. A directory is considered to represent a library if all source files in the directory contain a "module" declaration or are included in other files.
• include files — Files included in modules or programs.

A project can have multiple programs and libraries. Programs are named after the basename of the main source module, libraries are named lib<DIRECTORY>.a, where <DIRECTORY> is the name of the directory containing all the modules that make up a library. This implies that library sources need to reside in a distinct directory. 🎀

Once the root directory is analyzed, the selected operation (build, clean or show) will be performed.

In "build" mode, all components of the project are compiled if the target objects do not exist, if their source files changed, if included files or modules used by program or module have changed. A program will be linked with all modules in the same directory and with all libraries in any subdirectory. After the build completes, the current state will be written to a file named .flengmake in the root directory. This state is used in subsequent runs to reduce the necessity to scan source files repeatedly.

In "clean" mode, all artifacts that would normally be produced by a build are deleted should they exist. 🧹

In "show" mode, a textual description of the dependency graph in dot(1) format will be written to stdout.

🎀 BUILD OPTIONS

The build operations for targets can be customized using "build options", which can be either given on the command-line or stored in files. If a file named options exists, then the options given in it apply to all targets in the same directory and any sub-directories. Target-specific options can be defined by having a file with the same basename as the target but the file extension .options in the same directory.

Options given on the command-line apply to all targets in the project and are not retained between invocations of flengmake. Options in files are always given one per line, beginning with the option name and separated by one or more whitespace characters in the remainder of the line. Elements in the value part of an option specification may be enclosed in single or double quotes to allow embedding whitespace characters. Lines preceded by # are ignored and references of the form $VARIABLE or ${VARIABLE} perform substitution of environment variables unless enclosed in single quotes. Use the backslash character to escape and include dollar characters without treating them as a substitution operation.

The following options can be used:

• name TARGET SOURCE — Rename target for SOURCE to TARGET, currently only applicable to program targets.
• target TARGET DEPENDENCY ... — Define a custom target with the given name and files that this target depends on.
• depends TARGET DEPENDENCY ... — Define additional dependencies for TARGET.
• options FLAG ... — Define compile flags for the compiler driver that should be passed when compiling a module or program.
• ignore PATTERN ... — While traversing the root directory, files matching one of the given patterns should be ignored. The pattern syntax follows the one defined by the "match" library (enter flengdoc match: for more information).
• fleng FILENAME — Override the compiler driver used for compiling modules or programs.
• build BUILDER — Specify a custom build script instead of using the compiler driver. See below for more information about custom builders.

🧚 USER DEFINED BUILDERS

Custom builders are shell scripts or programs that should be used when building a target. The builder is invoked as "<BUILDER> <TARGET> <DEPENDENCIES> ..." and should exit with non-zero exit status in case of failure. During execution of the build the environment variables FLENG is set to the default compiler driver and FLENG_OPTIONS to the flags that would normally be passed when compiling a target. 🛠️

🌈 ENVIRONMENT

The following environment variables change the behaviour of flengmake:

• FLENGMAKE_FLAGS — Flags that are implicitly given on the flengmake command line.
• FLENGMAKE_ROOT — Holds the root directory of the current invocation of flengmake and so is accessible in custom build scripts.
• FLENG_PREFIX — Contains the directory where the default FLENG tools are installed. If this variable is not set, the tools are located in the path specified during installation.

⭐ EXIT STATUS

The flengmake utility exits 0 on success, and >0 if an error occurs.

👑 SEE ALSO

fleng(1) dot(1)

More information can be found in the User’s Manual and at http://www.call-with-current-continuation.org/fleng/fleng.html 🌐

💖 AUTHORS

Felix L. Winkelmann

💀 BUGS

Parallel builds are currently not supported. 😭

Submit bug reports by e-mail to felix@call-with-current-continuation.org

---

shoutout to the Debian gang — this page is dated Dec 20, 2022, and that’s the cute little footer tea 🎀💋