Merge pull request #303 from PRUNERS/issue302-ninja-build

Issue302 ninja build

Makefile

@@ -115,7 +115,7 @@ install: $(TARGET)
 	mkdir -m 0755 -p $(INST_BINDIR)
 	mkdir -m 0755 -p $(INST_LIBDIR)
 	mkdir -m 0755 -p $(INST_INCLUDEDIR)
-	mkdir -m 0755 -p $(INST_SHAREDIR)/scripts
+	mkdir -m 0755 -p $(INST_SHAREDIR)/scripts/experimental
 	mkdir -m 0755 -p $(INST_SHAREDIR)/doc
 	mkdir -m 0755 -p $(INST_SHAREDIR)/data/tests
 	mkdir -m 0755 -p $(INST_SHAREDIR)/data/db
@@ -128,6 +128,8 @@ install: $(TARGET)
 	install -m 0644 $(HEADERS) $(INST_INCLUDEDIR)
 	install -m 0755 $(SCRIPT_DIR)/flit.py $(INST_SHAREDIR)/scripts/
 	install -m 0755 $(SCRIPT_DIR)/flit_*.py $(INST_SHAREDIR)/scripts/
+	install -m 0755 $(SCRIPT_DIR)/experimental/flit_*.py $(INST_SHAREDIR)/scripts/experimental/
+	install -m 0644 $(SCRIPT_DIR)/experimental/ninja_syntax.py $(INST_SHAREDIR)/scripts/experimental/
 	install -m 0644 $(SCRIPT_DIR)/flitutil.py $(INST_SHAREDIR)/scripts/
 	install -m 0644 $(SCRIPT_DIR)/flitelf.py $(INST_SHAREDIR)/scripts/
 	install -m 0644 $(SCRIPT_DIR)/README.md $(INST_SHAREDIR)/scripts/

documentation/README.md

@@ -19,6 +19,7 @@
 * [Benchmarks](benchmarks.md)
 * [Database Structure](database-structure.md)
 * [Analyze Results](analyze-results.md)
+* [Experimental Features](experimental-features.md)
 * Extra Tools
     * [Autogenerated Tests](autogenerated-tests.md)
     * [Test Input Generator](test-input-generator.md)

documentation/analyze-results.md

@@ -4,7 +4,7 @@
 |
 [Table of Contents](README.md)
 |
-[Next](autogenerated-tests.md)
+[Next](experimental-features.md)
 
 The analysis functionality is broken at the moment.  You can expect to be here
 some instructions on how to generate useful charts from the gathered data.
@@ -13,4 +13,4 @@ some instructions on how to generate useful charts from the gathered data.
 |
 [Table of Contents](README.md)
 |
-[Next](autogenerated-tests.md)
+[Next](experimental-features.md)

documentation/autogenerated-tests.md

@@ -1,6 +1,6 @@
 # Autogenerated Tests
 
-[Prev](analyze-results.md)
+[Prev](experimental-features.md)
 |
 [Table of Contents](README.md)
 |
@@ -23,7 +23,7 @@ directory (let's say it is located at `project/flit-tests`).
 FLiT/gensrc/gensrc.py --outdir project/flit-tests/tests 1
 ```
 
-[Prev](analyze-results.md)
+[Prev](experimental-features.md)
 |
 [Table of Contents](README.md)
 |

documentation/experimental-features.md

@@ -0,0 +1,83 @@
+# Experimental Features
+
+[Prev](analyze-results.md)
+|
+[Table of Contents](README.md)
+|
+[Next](autogenerated-tests.md)
+
+There are experimental featues 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-generator)
+
+## Ninja Generator
+
+[Ninja](https://ninja-build.org) 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
+
+```bash
+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](analyze-results.md)
+|
+[Table of Contents](README.md)
+|
+[Next](autogenerated-tests.md)

documentation/flit-command-line.md

@@ -27,6 +27,7 @@ Possible subcommands:
 * [flit make](#flit-make): Run flit tests locally and add results to the database
 * [flit import](#flit-import): Imports test results into an SQLite3 database
 * [flit bisect](#flit-bisect): Assign variability blame to files and functions
+* [flit experimental](#flit-experimental): Access to experimental features
 
 ## flit help
 
@@ -199,6 +200,18 @@ bisect invocation if the given compiler is found within `flit-config.toml`.
 
 Call `flit bisect --help` for more documentation.
 
+
+## flit expeirmental
+
+There may or may not be any experimental features currently available.  These
+features are available by the `flit experimental` command.  Please call `flit
+experimental` to see the documentation of what experimental features are
+available.
+
+You may also read the documentation on
+[experimental features](experimental-features.md).
+
+
 [Prev](litmus-tests.md)
 |
 [Table of Contents](README.md)