limbus-buildgen

Introduction

limbus-buildgen generates build files for small C/C++ code-bases that do not need a very complicated build process. Thus this library can be kept small which makes it easy to test and port to other platforms.

The project consists of a set of Common.js modules written in ES5.1 which can be imported into your project. A CLI front-end is also available to generate build files without additional code.

Table of contents

• Installation
• Using the CLI
• Configuration
• Javascript API
• Continuous Integration
• Building from source
• Development
• Roadmap
• Copyright

Installation

Using the CLI

Usage: limbus-buildgen [flags] <path to JSON configuration file>

Options:

  --help                          output usage information
  --host <host>                   override the configured target host
  --buildFile <path>              specify the path and filename for the
                                  generated build file (default: ./Makefile)

Configuration

The JSON configuration files support the following properties:

Required

Property	Description
type	Specifies the type of project to build.
host	Specifies the target host, i.e. the desired OS & compiler that the makefile should compile with.
input	Specifies a list of source files.
outputName	Specifies the name of the final executable.

Optional

Property	Description
outputPath	Specifies a path to prepend to the outputName. It defaults to the build directory.
includePaths	Specifies where to find header files to include.
compilerFlags	Specifies any extra compiler flags that will be passed to the compiler as is.
linkerFlags	Specifies any extra linkers flags that will be passed to the linker as is.
libraries	Specifies any libraries to link with when building an application or dynamic library.

Example configuration file

configuration.json

{
    "type": "application",
    "host": "darwin-clang",
    "files": [
        "main.c"
    ],
    "outputName": "my-application",
 
    "outputPath": "some/path",
    "includePaths": [
        "include/"
    ],
    "compilerFlags": "-g -O0 -coverage",
    "linkerFlags": "-coverage",
    "libraries": [
        "png"
    ]
}

A makefile for the above example can be generated using:

limbus-buildgen configuration.json

Configuration Properties

type

There are three types of projects which can be generated:

Type	Description
application	An executable application
static-library	A library that can be linked to at compile-time
dynamic-library	A library that can be linked to at run-time

host

The following host identifiers can be used to target the corresponding operating system & compiler:

Identifier	Target OS	Compiler
linux	Linux	GNU GCC
linux-clang	Linux	Clang/LLVM
linux-gcc	Linux	GNU GCC
darwin	Mac OS X	Clang/LLVM
darwin-clang	Mac OS X	Clang/LLVM
darwin-gcc	Mac OS X	GNU GCC
win32	Windows	CL
win32-cl	Windows	CL
freebsd	FreeBSD	Clang/LLVM
freebsd-clang	FreeBSD	Clang/LLVM
freebsd-gcc	FreeBSD	GNU GCC

input

The input property takes an array of strings. Each string contains a path to a input file relative to the build directory.

outputName

The property outputName takes a string with the name of the final executable or library. Depending on the compiler and type, the name given by outputName is prepended, appended or both to form a system specific file name.

Given a configuration with "outputName": "file" the following table shows the resulting file name:

Compiler	Type	File name
GNU GCC	application	file
GNU GCC	static-library	libfile.a
GNU GCC	dynamic-library	libfile.so
Clang	application	file
Clang	static-library	libfile.a
Clang	dynamic-library	libfile.so
CL	application	file.exe
CL	static-library	file.lib
CL	dynamic-library	file.dll

The output name cannot be a path.

outputPath

The outputPath property takes a string with a path to be prepended to the outputName to give the final location of the executable or library when built. The path can have a trailing path separator but does not require one.

includePaths

The includePaths property takes an array of strings. Each string contains a path relative to the build directory to use to include header files.

compilerFlags

Compiler flags are added to the compile command.

linkerFlags

Linker flags are added to the link command. Which link command is used depends on the type and compiler specified. This needs to be taken into account when flags are added to the configuration.

The following table describes what commands are used and how flags are inserted for all compiler/type combinations:

Compiler	Type	Command
GNU GCC	application	gcc -o executable file.o [flags]
GNU GCC	static-library	ar rcs[flags] liblibrary.a file.o
GNU GCC	dynamic-library	gcc -shared -o liblibrary.so file.o [flags]
Clang	application	clang -o executable file.o [flags]
Clang	static-library	ar rcs[flags] liblibrary.a file.o
Clang	dynamic-library	clang -shared -o liblibrary.so file.o [flags]
CL	application	cl /Feexecutable.exe file.obj [flags]
CL	static-library	lib /OUT:library file.obj [flags]
CL	dynamic-library	link /DLL /OUT:library file.obj [flags]

libraries

The libraries property takes an array of strings. Each string contains a path to a library file to link to.

Paths

All paths in the configuration are given as POSIX paths. The generators take care of adapting the paths to the final build operating system.

. specifies the current directory. .. specifies the parent directory of the current one. / separates each directory with the last part giving the target file or directory of the path.

Javascript API

Generate Makefiles

var makefile_generator = require('../source/makefile-generator');
 
// Returns a string with the generated makefile.
var makefile = makefile_generator.generate({
    // The following options are required:
    // Specifies the type of project to build, can be either 'application', 'dynamic-library' or 'static-library'.
    type: 'application',
    // Specifies the target host, i.e. the desired OS & compiler that the makefile should compile with.
    host: 'darwin-clang',
    // Specifies a list of source files.
    files: [
        'main.c'
    ],
    // Specifies the name of the final executable.
    outputName: 'my-application',
 
    // The following options are optional:
    // Specifies a path to prepend to the outputName.
    outputPath: "some/path",
    // Specifies where to find header files to include.
    includePaths: [
        'include/'
    ],
    // Specifies any extra compiler flags that will be passed to the compiler as is.
    compilerFlags: '-g -O0 -coverage',
    // Specifies any extra linker flags that will be passed to the linker as is.
    linkerFlags: '-coverage',
    // Specifies any libraries to link with when building an application or dynamic library.
    libraries: [
        'png'
    ]
});

Continuous Integration

Unit- & integration tests are automatically run against several combinations of target hosts, build configurations and Node.js versions at every push.

Integration matrix

Target Host	Build Status	Built Configurations	Node.js Versions
linux-clang		x64	5.9.0, 4.4.0
linux-gcc		x64	5.9.0, 4.4.0
darwin-clang		x64	5.9.0, 4.4.0
darwin-gcc		x64	5.9.0, 4.4.0
win32-cl		x86 Release, x64 Release	4.4.0
freebsd-clang
freebsd-gcc

FreeBSD is tested from time to time during development of new features but as there is currently no continuous integration on a FreeBSD host it should be considered less stable than the other target hosts.

Building from source

For all platforms, open a terminal and run the following command in the root project directory:

make

limbus-buildgen compiles using build files that it generated itself. To re-generate the makefiles run utility-scripts/generate_build_files.sh on a Unix-like OS after building.

Dependencies

There are very few dependencies and they are downloaded automatically when built. However it is assumed that a standard C compiler is installed. (For Windows users this means having Visual Studio or the Windows SDK installed in their default installation directory. Most Unixes come with a C compiler suite.)

Windows users will need PowerShell 3.0+ installed (which comes with Windows 7 SP1 or later) to automatically download the dependencies. If this is not possible, see Download dependencies manually

Download dependencies manually

Duktape is used for Javascript execution. You can download the Duktape 1.4.0 release package from http://duktape.org/ and extract it into dependencies/duktape-1.4.0.

Development

For development you need some extra development dependencies. Install them using NPM with:

npm install

Test

limbus-buildgen performs testing using mocha and should.js.

Run both unit- and integration tests using

npm test

To run each separately, use npm run unit-test for unit tests and npm run integration-test for integration tests.

Code coverage

limbus-buildgen analyzes code coverage using blanket.js. To produce a report, run:

npm run-script coverage

This will generate a file named coverage.html in the project root directory which can be viewed in a browser.

Roadmap

Planned for a 0.5 version

This release is intended to streamline the user experience and produce a done release that is not fully feature-complete. It will take the project from an alpha phase into beta.

• Provide an integrated executable for the front-end
• Provide npm packages for both executable and libraries
• Create release bundled with dependencies
• Override all configuration properties using flags
• Complete documentation
• Modify makefile generator so that makefiles make use of make's "implicit variables"
• Library include paths
• Provide configuration overrides for when different arguments are passed

Planned for a 0.6 release

This release will implement cross compilation to mobile devices.

• Cross compilation to iOS
• Cross compilation to Android

Planned for a 0.7 release

This release will implement cross compilation to web browsers through Emscripten.

• Emscripten compiler support

Planned for a 0.8 release

This release will implement the rest of the features to make it feature-complete.

• A Visual Studio project generator

Towards a 1.0 release

This release will stabilize the project to make it ready for production.

• Continuous integration for all supported targets

Further into the future

Features which aren't needed for feature-completeness but are nice to have.

• Cross compilation to Windows using MinGW
• Modify makefile to find compilers and use whichever is available.
• Support for more compiler suites:
  • AMD's Open64
  • Intel's C++ compiler
  • MinGW
  • Solaris Studio
• Support for more build systems:
  • Ninja
  • Code::Blocks
  • JetBrain's CLion
  • NetBeans C++

Copyright

limbus-buildgen - A "build anywhere" C/C++ makefile/project generator.

Written in 2014-2016 by Jesper Oskarsson [e-mail]

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.