Revision 0235e325b60dcbd41bc82cdee55b5e3940e70b3e authored by Matthias J. Kannwischer on 29 September 2021, 02:52:07 UTC, committed by rpls on 01 October 2021, 16:14:07 UTC
1 parent 9896316
README.md
# MuPQ build system
The build system consists of several platform-dependent (not part of this repo)
and platform independent modules. The build system assumes, that the `mupq`
repository is a submodule of the specific platform dependent repository, e.g.,
`pq{m4,m3,riscv}`. The build system is split into the following modules.
- `mupq/mk/config.mk`: The initial configuration script. It sets up all the
basic platform independent compilation flags. It will also include the
platform dependent configuration script named after the value of the
`PLATFORM` variable. This configuration file also contains
[mechanism](#variable-retention) for managing configuration variables that
should trigger a `clean`.
- `mupq/mk/<PLATFORM>.mk`: This script sets up all the platform dependent
compilation and linker flags. This file may contain a list of schemes to be
skipped, meant for schemes that cannot run on the platform for any reason.
- `mupq/mk/rules.mk`: Contains all the pattern rules for compiling and linking
source code.
- `mupq/mk/schemes.mk`: This script locates all the schemes, all their
implementations and defines `make` targets all the objects, libraries and
benchmark executables. The mechanism for locating schemes is defined
[here](#locating-implementations).
- `mupq/mk/host-crypto.mk`: Defines a host-library for symmetric cryptographic
algorithms that can be used by all the schemes. This host-library is platform
independent and used to generate the test vectors.
- `mk/crypto.mk`: Defines the platform dependent symmetric crypto library. The
library is compiled twice, once with- and once without profiling code enabled
(used for profiling the time spent hashing / encrypting).
## User Configuration Variables
The build system can be parameterized by the user with the following variables:
- `PLATFORM=<yourplatform>` (required): The chosen target board/platform.
- `DEBUG=1`: Compile all code without optimization and with debug symbols.
- `OPT_SIZE=1`: Optimize all code for size (otherwise the default is `-O3`).
- `LTO=1`: Enable link-time optimization.
- `AIO=1`: Use all-in-one compilation of schemes, i.e. pass all sources instead
of compiled modules to the linking step (this can, in some cases, be faster
than link-time optimization).
Each platform may also define further variables.
## Output folders
The resulting binaries are placed in the following folders:
- `obj`: The compiled objects and libraries.
- `obj-host`: The compiled host-objects and host-libraries.
- `elf`: The linked `elf` executables of all the benchmarks.
- `bin`: A flashable binary file (if required by the target platform).
- `bin-host`: The linked executables for the host, e.g., test vector generators.
## Variable Retention
The build system will retain the value of certain variables by generating a
`obj/.config.mk` that contains the values of all retained variables. The
variables that will be retained are defined by the `RETAINED_VARS` variable. An
error will be triggered promting the user to run `make clean`, if any of these
variables appear to be changed from the initial configuration value. This is
meant for configuration variables that affect the compilation result, such as
optimization flags.
## Locating Implementations
Each time `make` is run, a set of folders will be searched for implementations
to define targets for libraries and benchmark executables. Schemes are meant to
located in the following folders:
- `crypto_{kem,sign}/`: Platform dependent KEM/signature schemes.
- `mupq/crypto_{kem,sign}/`: Platform independent KEM/signature schemes.
- `mupq/pqclean/crypto_{kem,sign}/`: Platform independent KEM/signature schemes
from the PQClean project.
Each scheme is placed in a subfolder named after a scheme, with each
implementation in its own folder, i.e.,
`crypto_{kem,sign}/<scheme>/<implementation>/<sourcefiles.{c,h,s}>`.
The `mupq/mk/schemes.mk` will automatically find these folders and define
targets for each implementation. The name of each implementation is simply
derived from its path, with `/` replaced by `_`. The following targets are
defined:
- A library `obj/lib<schemename>.a`
- A self test `elf/<schemename>_test.elf`
- A speed test `elf/<schemename>_speed.elf`
- A hashing profiling test `elf/<schemename>_hashing.elf`
- A stack size test `elf/<schemename>_stack.elf`
- A test vector test `elf/<schemename>_testvector.elf`
- If the implementation is platform independent, a test vector generator
`bin-host/<schemename>_testvectors` will be defined.
- `bin/*.bin` / `bin/*.hex` files are generated automatically for each `elf`
file, if required by the flashing tools for the platform.
The locating mechanism of the script utilizes the capability of `make` to
[(re-)make included makefiles](https://www.gnu.org/software/make/manual/html_node/Remaking-Makefiles.html).
The script will automatically generate a `obj/.schemes.mk` files, that contains
the two variables `KEM_SCHEMES` and `SIGN_SCHEMES`, each of which is just a list
of paths to all implementations. If this file does not exist, it will be
generated by two calls to the `find` utility that will enumerate all
implementations within the search paths mentioned above. The `obj/.schemes.mk`
is furthermore marked "phony", triggering `make` to re-generate it everytime it
is called.
This location mechanism will be skipped, if the `IMPLEMENTATION_PATH` variable
is defined (all `make` invocations by the python benchmarking scripts will
automatically include this variable). In this case, only the single
implementation pointed to by this variable will be compiled.
Computing file changes ...