From 3c2a2347b9487cb7b078702d381f2bc0090f8d3a Mon Sep 17 00:00:00 2001 From: Michael Bentley Date: Thu, 22 Jun 2017 13:25:29 -0700 Subject: [PATCH] Docs: move full config file example to the end --- documentation/flit-configuration-file.md | 139 ++++++++++++----------- 1 file changed, 73 insertions(+), 66 deletions(-) diff --git a/documentation/flit-configuration-file.md b/documentation/flit-configuration-file.md index 93f8488c..8ca2fa00 100644 --- a/documentation/flit-configuration-file.md +++ b/documentation/flit-configuration-file.md @@ -9,7 +9,14 @@ The FLiT configuration file is called `flit-config.toml`. It is written in the [TOML](https://github.com/toml-lang/toml) specification. -Here is a full example configuration file: +Here I have an example configuration file. I will go through it section by +section. If you want to see the full configuration file, it is at the end of +this page. + +_Note: there are no default values for these fields. You must specify all +fields for an entry to be valid. If in doubt, you can use [flit +check](flit-command-line.md#flit-check) to verify your configuration file is +valid._ ```toml [database] @@ -18,19 +25,47 @@ username = 'mbentley' address = 'localhost' type = 'postgres' port = 5432 +``` + +Above we specify the information for the database connection. Since +it is not very secure to store passwords in the configuration file, +you will be prompted for the password at the time of execution. Right +now, `postgres` is the only database type that is supported, but more +are to come. +```toml [[hosts]] name = 'my.hostname.com' flit_path = '/usr/bin/flit' config_dir = 'project/flit-tests' +``` + +Now we start specifying information of the first host called `my.hostname.com`. +The `flit_path` is the path of the `flit` command-line tool at this host. The +`config_dir` is the directory where this configuration file is located on the +host. For now, it is expected that each machine already has a copy of the +tests with the same configuration file and that their location is documented +here. If needed, this may be revisited. + +For any variable that specifies a relative path, the relative path is always +with respect to the current user's home directory. +```toml [hosts.ground_truth] compiler = 'g++' optimization_level = '-O0' switch = '' +``` + +Each host has a ground truth run to use as comparisons when doing analysis. +The `compiler` field here needs to match the `name` of the compiler specified +later in the `[[hosts.compilers]]`. Also, the `optimization_level` and +`switch` need to be available in the `optimization_levels` and `switches` for +the compiler with the matching name. +```toml [[hosts.compilers]] binary = 'g++' @@ -45,7 +80,26 @@ switch = '' '-fassociative-math', '-mavx2 -mfma', ] +``` + +Here we specify the first compiler for the first host. Since binary here is a +simple name, it will get the executable `g++` from the system `PATH`. If you +really mean you want to have a compiler that is located in your home directory, +you can do `./g++`. + +The `type` parameter can be one of + +* `gcc` +* `clang` +* `intel` +* `cuda` + +The `optimization_levels` and `switches` will be combined as a cartesian +product and each possible pairing will become a compilation performed by FLiT. +For a list of all possible flags for each compiler type, see [Available +Compiler Flags](available-compiler-flags.md). +```toml [[hosts.compilers]] binary = 'my-installs/g++-7.0/bin/g++' @@ -60,7 +114,14 @@ switch = '' '-mavx2 -mfma', '-funsafe-math-optimizations', ] +``` + +Here it is demonstrated that you can specify a second version of `g++` +with different optimization levels and switches from the first +version. It is simply required that the compiler name be unique for +this host. +```toml [[hosts.compilers]] binary = 'clang++' @@ -81,7 +142,13 @@ switch = '' '-mavx2 -mfma', '-march=core-avx2', ] +``` +We also specify a third compiler `clang++`, again with different flags. So for +the host `my.hostname.com`, we have three compilers configured: `g++`, +`g++-7.0`, and `clang`. + +```toml [[hosts]] name = 'other.hostname.com' @@ -107,13 +174,12 @@ switch = '' ] ``` -We will now go through the elements of this configuration file piece by piece -and explain what they represent. +Here it is demonstrated that you can specify another host. This one is called +`other.hostname.com` with a single compiler named `intel`. + +## Full Configuration File -_Note: there are no default values for these fields. You must specify all -fields for an entry to be valid. If in doubt, you can use [flit -check](flit-command-line.md#flit-check) to verify your configuration file is -valid._ +Combining all of the above sections together, here is the full example configuration file: ```toml [database] @@ -122,47 +188,19 @@ username = 'mbentley' address = 'localhost' type = 'postgres' port = 5432 -``` - -Above we specify the information for the database connection. Since -it is not very secure to store passwords in the configuration file, -you will be prompted for the password at the time of execution. Right -now, `postgres` is the only database type that is supported, but more -are to come. -```toml [[hosts]] name = 'my.hostname.com' flit_path = '/usr/bin/flit' config_dir = 'project/flit-tests' -``` - -Now we start specifying information of the first host called `my.hostname.com`. -The `flit_path` is the path of the `flit` command-line tool at this host. The -`config_dir` is the directory where this configuration file is located on the -host. For now, it is expected that each machine already has a copy of the -tests with the same configuration file and that their location is documented -here. If needed, this may be revisited. - -For any variable that specifies a relative path, the relative path is always -with respect to the current user's home directory. -```toml [hosts.ground_truth] compiler = 'g++' optimization_level = '-O0' switch = '' -``` - -Each host has a ground truth run to use as comparisons when doing analysis. -The `compiler` field here needs to match the `name` of the compiler specified -later in the `[[hosts.compilers]]`. Also, the `optimization_level` and -`switch` need to be available in the `optimization_levels` and `switches` for -the compiler with the matching name. -```toml [[hosts.compilers]] binary = 'g++' @@ -177,23 +215,7 @@ the compiler with the matching name. '-fassociative-math', '-mavx2 -mfma', ] -``` - -Here we specify the first compiler for the first host. Since binary here is a simple name, it will get the executable `g++` from the system `PATH`. If you really mean you want to have a compiler that is located in your home directory, you can do `./g++`. - -The `type` parameter can be one of - -* `gcc` -* `clang` -* `intel` -* `cuda` - -The `optimization_levels` and `switches` will be combined as a cartesian -product and each possible pairing will become a compilation performed by FLiT. -For a list of all possible flags for each compiler type, see [Available -Compiler Flags](available-compiler-flags.md). -```toml [[hosts.compilers]] binary = 'my-installs/g++-7.0/bin/g++' @@ -208,14 +230,7 @@ Compiler Flags](available-compiler-flags.md). '-mavx2 -mfma', '-funsafe-math-optimizations', ] -``` - -Here it is demonstrated that you can specify a second version of `g++` -with different optimization levels and switches from the first -version. It is simply required that the compiler name be unique for -this host. -```toml [[hosts.compilers]] binary = 'clang++' @@ -236,13 +251,7 @@ this host. '-mavx2 -mfma', '-march=core-avx2', ] -``` -We also specify a third compiler `clang++`, again with different flags. So for -the host `my.hostname.com`, we have three compilers configured: `g++`, -`g++-7.0`, and `clang`. - -```toml [[hosts]] name = 'other.hostname.com' @@ -268,8 +277,6 @@ switch = '' ] ``` -Here it is demonstrated that you can specify another host. This one is called -`other.hostname.com` with a single compiler named `intel`. [Prev](flit-command-line.md) |