vMakefiles

vMakefiles are Lua scripts which make use of vMake to build a project.

They do so by employing the following:

Prologue

For ease of use, a vMakefile should be executable directly, and to avoid any issues, including vMake is the first thing it should do:

#!/usr/bin/env lua
require "vmake"

Epilogue

After all your code and declarations, you have to tell vMake to do its job:

vmake()

Declarations

Inside a vMakefile, you may declare the following:

• Architectures
• Configurations
• Projects
• Global data
• Command-line options
• Output directory
• Defaults

The absolute minimum declaration is one project.
If there is more than one, a default must be specified.

There are more objects that can be declared, but must be within another:

• Components
• Rules

Besides these declared objects, you can use the following classes:

• List
• Path

The following abstractions are provided and preferred for maximum compatibility:

• fs (file system)
• sh (shell)
• env (environment variables)

Also, you may use Lambdas in most parts.

Execution

First of all, make sure your vMakefile is executable:

chmod +x vmakefile.lua

The run this for more information:

./vmakefile.lua --help

Examples

Here is a condensed example for building a C++ project:

#!/usr/bin/env lua
require "vmake"

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Configurations
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

Configuration "debug" {
    Data = {
        Opts_CXX = List "-fno-omit-frame-pointer -g3",
    },
}

Configuration "release" {
    Data = {
        Opts_CXX = List { },
    },
}

Configuration "profile" {
    Data = {
        Opts_CXX = List { },
    },

    Base = "release",
}

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Architectures
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

Architecture "any"

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Toolchain
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

GlobalData {
    CXX   = "c++",
    LD    = "c++",
}

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Options and Parameters
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

GlobalData {
    Opts_CXX_Precompiler = function(_)
        local res = List {
            "-DMYPROJ",
            "-DMYPROJ__ARCH=" .. _.selArch.Name,
            "-DMYPROJ__CONF=" .. _.selConf.Name,
        }

        for arch in _.selArch:Hierarchy() do
            res:Append("-DMYPROJ__ARCH_" .. string.upper(arch.Name))
        end

        for conf in _.selConf:Hierarchy() do
            res:Append("-DMYPROJ__CONF_" .. string.upper(conf.Name))
        end

        return res
    end,

    Opts_CXX_Common = LST "-pipe @Opts_CXX_Precompiler @selConf.Data.Opts_CXX",
}

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Main File Locations
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

GlobalData {
    MyProjPath = DAT "@outDir + 'vermc'",
}

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Projects
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

ManagedProject "MyProj" {
    Languages = { "C++" },
    Target = "Executable",

    Description = "My Awesome Project",

    Data = {
        BinaryPath = DAT "@MyProjPath",

        Opts_CXX = LST "-std=gnu++11 -flto @Opts_CXX_Common @Opts_Includes",
        Opts_LD = LST "-fuse-linker-plugin @Opts_CXX",
    },

    Directory = "myproj",

    Output = DAT "@MyProjPath",

    CreateMissingDirectoriesRule(true),
}

--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
--  Wrap up
--  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --

Default "MyProj" "any" "debug"

vmake()

Don't expect to understand this without reading the documentation.

Running ./vmakefile.lua --help on this will result in:

Usage: vmakefile.lua [options] [--] [project, architecture & configuration]

    --help  -h
        Displays available command-line options.

    --version  -v
        Displays brief information about vMake.

    --debug
        Enables some debugging features, making the code more strict,
        exposing possibly unwanted behaviour.

    --print
        Prints all the defined data and the computed work graph
        (a directed dependency graph) which would otherwise be executed.

    --clean  -c
        Cleans the output directory.
        Will not perform a build unless `--full` is also specified.

    --full  -f
        Indicates that work items should be executed even if they
        are considered up-to-date.

    --jobs=<integer>  -j <integer>
        Number of jobs to use for rule action execution.
        0 means unlimited. Defaults to 1, meaning serial execution.

    --parallel-bar
        Enables the display of a progress bar when using GNU Parallel.

    --silent
        Omits unsilenced shell commands from standard output.

    --verbose
        Outputs more detailed information to standard output,
        such as the steps taken by vMake and all shell commands executed.

Projects:
    - MyProj
        My Awesome Project

Architectures:
    - any

Configurations:
    - debug
    - release
    - profile -> release

Powered by vMake v1.6.0 [1006000] (c) 2016 Alexandru-Mihai Maftei, running under Lua 5.2

When running ./vmakefile.lua --print on a simple (one C++ file) project of mine, the output looks like this:

[Project Compiler]
  - Description: --NONE--
  - Directory: compiler
  - Dependencies: 0 items: [List Print table: 0x12345610 ]
  - Output: 1 items: [List Print table: 0x12345660 .vmake/any.debug/vermc ]
  - Rules: (4)
    [Rule Compile C++ of [Project Compiler]]
    [Rule Precompile C++ Header of [Project Compiler]]
    [Rule Link Executable of [Project Compiler]]
    [Rule Create Missing Directories of [Project Compiler]]
  - Components: NONE

[Work Load for [Project Compiler] | 1 items]
  - Level -1
  - Prerequisites: NONE
  - Items: (1)
    [Work Item for .vmake/any.debug/vermc | [Rule Link Executable of [Project Compiler]]]
      - Level -1
      - Prerequisites: (2)
        [Work Item for .vmake/any.debug/compiler/main.cpp.o | [Rule Compile C++ of [Project Compiler]]]
          - Level -1
          - Prerequisites: (1)
            [Work Item for .vmake/any.debug/compiler | [Rule Create Missing Directories of [Project Compiler]]]
              - Level -1
              - Prerequisites: NONE
              - Sources: NONE
          - Sources: (2)
            compiler/main.cpp
            .vmake/any.debug/compiler
        [Work Item for .vmake/any.debug | [Rule Create Missing Directories of [Project Compiler]]]
          - Level -1
          - Prerequisites: NONE
          - Sources: NONE
      - Sources: (2)
        .vmake/any.debug/compiler/main.cpp.o
        .vmake/any.debug