BuildSystem

• The CONTEXT environment variable specifies the build context within which the build process is executed:

  Context	Description
  native	The default, native build context
  docker	A containerised build context, offered by an architecture-specific Docker image

  Note that:

  • Up to a point, it is reasonable to view this mechanism as somewhat over-engineered. In a sense it is, but, equally, there are some important motivations for supporting it. For example, use of Travis CI as a continuous integration platform places a time-limit on the build process. This limit is too short to allow bespoke tool-chains (e.g., for XCrypto) to be built, a problem which is addressed by using a pre-built, i.e., containerised, alternative.

  • Each architecture-specific Docker image is built using the content housed in ${REPO_HOME}/src/docker. However, there is no need to do this manually: a pre-built image can (and will) be pulled from Docker Hub by the build process as needed.

• The ARCH environment variable specifies the target architecture to consider, identifiers for which are one of the following:

  Architecture	Description
  native	Architecture-agnostic: whatever the default, native GCC targets
  riscv	Architecture-specific: RISC-V RV32IMAC
  riscv-xcrypto	Architecture-specific: RISC-V RV32IMAC plus XCrypto

• The KERNELS environment variable specifies a list of kernels to consider, identifiers for which are one of the following:

  Kernel	Variant	Description	native	riscv	riscv-xcrypto
  block/aes	sbox		o	x	o
  block/aes	packed		o	x	x
  block/aes	ttable		o	x	x
  block/prince			o	x	x
  block/sparx			o	x	x
  hash/keccak			o	x	x
  hash/sha1			o	x	x
  hash/sha2			o	x	x
  mp/limb			o	x	x
  mp/mpn			o	o	o
  mp/mpz			o	x	x
  mp/mrz			o	x	x
  stream/chacha20			o	x	o

  Note that:

  • The variant column toward the left-hand side of the table highlights where a major variant of a given kernel is available: the variant is selected via configuration symbols for said kernel, vs. being classed a separate kernel.

  • The columns toward the right-hand side of the table highlight where specific support for a given target architecture is available: o means an architecture-specific (typically assembly language) implementation is available, whereas x means an architecture-agnostic (typically C) implementation is available.

  • A limited form of wildcard are supported: for example,

    • rather than hash/sha1 hash/sha2, one could use hash/sha*,
    • rather than hash/keccak hash/sha1 hash/sha2, one could use hash/*.

• Each target architecture requires several configuration files:

  1. ${REPO_HOME}/conf/${ARCH}/Dockerfile.in, which specifies a build script for the Docker build context,
  2. ${REPO_HOME}/conf/${ARCH}/conf.mk_docker, which specifies configuration, to the build system, about the Docker build context,
  3. ${REPO_HOME}/conf/${ARCH}/conf.mk_kernel which specifies configuration, to the build system, about the kernel and hence library,
  4. ${REPO_HOME}/conf/${ARCH}/conf.mk_toolchain which specifies configuration, to the build system, about the tool-chain used to build the library and test suite.

• A given kernel implementation may be configurable via the second class of configuration file, st. a family of implementations can be selected between:

  • the configuration header file ${REPO_HOME}/src/libscarv/share/conf.h is populated using the configuration file, plus automatically generated content stemming from ${ARCH} and ${KERNELS}; it houses some documentation for each configuration symbol,

  • configuration symbols are made available in the source code via application of the C pre-processor, and follow a standard namespace, i.e.,

    LIBSCARV_CONF_${KERNEL}_${FUNCTION}_${PROPERTY}
    

    with some standard(ish) properties including the following:

    Property	Description
    ENABLE	enables (i.e., includes) functionality (assuming default is to disable it)
    DISABLE	disables (i.e., excludes) functionality (assuming default is to enable it)
    PRECOMP	support functionality via pre-computation
    EXTERN	uses a architecture-specific (typically assembly language) vs. architecture-agnostic (typically C) implementation of functionality

  • if a kernel cannot support a given configuration symbol, it must produce an error: it should be impossible to build the library using a configuration that would cause it to (silently) fail.