Skip to content

Latest commit

 

History

History
83 lines (61 loc) · 3.17 KB

experimental-features.md

File metadata and controls

83 lines (61 loc) · 3.17 KB

Experimental Features

Prev | Table of Contents | Next

There are experimental features not yet ready for prime-time. They may end up in flit as a permanent thing or they may be deemed too much work or not useful enough to become a full feature. Those features may stay as experimental features, or they may disappear entirely.

Currently supported experimental features:

Ninja Generator

Ninja is a build tool similar to GNU Make that focuses on simplicity, readability, speed, and parallelism. This experimental feature instead generates a build.ninja file to be compiled with ninja instead of the generated Makefile.

You can invoke the Ninja generator using

flit experimental ninja

Call it with the --help option to see more documentation about the usage and flags available.

Benefits

The generated build.ninja will be much larger than the generated Makefile. This is because each compilation is explicitly specified. For example, for a project with 120 source files and 305 specified compilations, the generated Makefile is only 20 Kilobytes. For that same project, the generated build.ninja file is 5.6 Megabytes at over 100,000 lines of generated code.

That extra used disk space may not seem like much of a benefit, but honestly, disk space is cheap, and 5.6 megabytes is nothing in comparison to the size of the compiled object files you are going to generate.

The true benefit is in the speed. If you want to do a clean of your build system, you may see a significant speedup with the Ninja system, despite the bigger file size. If you just want to view the help documentation using the help target, you will notice a significant improvement with the Ninja system. The actual build time for large projects is primarily dominated by the time it takes to compile, so for doing a full compilation, you may not notice much of a difference.

I'm not sure the benefits of this approach are significant enough to warrant the effort to make it a regular feature in FLiT. But it was a worthwhile experiment. Use this feature if you find use for it.

Inputs to the Ninja Generator

This generator reads in configuration information from flit-config.toml and reads variables defined in custom.mk. It then goes on to generate build.ninja from that information.

The custom.mk file does not need to exist. If it does, this tool will only read variables if they are present. The variables read from custom.mk are

  • SOURCE: list of source files
  • CXXFLAGS: C++ compile flags to use in all compilations
  • LDFLAGS: link flags to use in all compilations (e.g., "-L/usr/local/lib64")
  • LDLIBS: link libraries to use in all compilations (e.g., "-lm")
  • RUN_WRAPPER: command to wrap around the test executable when run

This custom.mk file is in GNU Makefile format. Any additional variables and rules defined inside are completely ignored. Feel free to use anything from GNU Make including if statements and things like $(wildcard ../src/*.cpp).

Prev | Table of Contents | Next