HOWTO-customize.build

<?xml version="1.0"?>
<!--
The eXtended Keccak Code Package (XKCP)
https://github.com/XKCP/XKCP

Implementation by Gilles Van Assche and Ronny Van Keer, hereby denoted as "the implementer".

For more information, feedback or questions, please refer to the Keccak Team website:
https://keccak.team/

To the extent possible under law, the implementer has waived all copyright
and related or neighboring rights to the source code in this file.
http://creativecommons.org/publicdomain/zero/1.0/
-->
<group>

<!--
# Introduction

We here explain how to create a custom build target in the XKCP. Some examples, which can be found below, illustrate the process.

Note that this file is included from Makefile.build, so the examples and anything tried here are accessible "for real" from make.


# Step 1: create a new target

First, choose a target name and add the corresponding XML tag. For the moment, we leave the inherits attribute empty:
    <target name="chosenName" inherits=""/>

The name can be anything. If it ends with .a, make will attempt to build a static library with that name. If it ends with .so (resp. with .dylib), make will build a dynamic library for Linux (resp. macOS). Otherwise, it will build a standalone executable. In all cases, one can add ".pack" when invoking make (but not in the target name) to get a tarball with the source files, instead of building it.


# Step 2: select the high-level services

In a second step, select the desired cryptographic functions and add the corresponding fragment keywords to the inherits attribute (separated by a space).

Please refer to lib/HighLevel.build for the list of supported cryptographic functions.


# Step 3: identify the required low-level services

Then, identify the permutations that the chosen cryptographic functions need.

Each cryptographic function implemented in the XKCP depends on a given permutation. It interacts with the permutation through an interface called SnP. Some functions further can take advantage of a parallel implementation of the permutation, in which case the interface is called PlSnP. The choice of high-level services therefore determines what we need as low-level services:
* Those that require Keccak-p[1600]: Kravatte, KangarooTwelve, FIPS202, SP800-185, Keccak{Sponge, Duplex, PRG} with rate + capacity = 1600
* Those that require Xoodoo: Xoofff, Xoodyak

For KangarooTwelve, SP800-185, Kravatte and Xoofff, the use of parallel implementations is recommended for best performances, but they can work without these.
* Optionally Keccak-p[1600]×2
* Optionally Keccak-p[1600]×4
* Optionally  Keccak-p[1600]×8.


# Step 4: select the implementation of the low-level services

Finally, for each of the required permutation (or parallel implementation thereof) identified in the previous step, select one implementation and add the corresponding fragment keywords to the inherits attribute (separated by a space).

Please refer to the file lib/LowLevel.build for the list of supported implementations.

-->

<!-- Examples -->

    <!-- Type "make Xoodyak-ARMv7M.pack" to get a tarball with the sources needed to compile Xoodyak on ARMv7M. -->
    <target name="Xoodyak-ARMv7M" inherits="Xoodyak Xoodoo-ARMv7M"/>

    <!-- Type "make libK12-AVX2.a" to build a library with KangarooTwelve with AVX2 code. Add ".pack" when invoking make to get a tarball with the source files instead. -->
    <target name="libK12-AVX2.a" inherits="KangarooTwelve K1600-AVX2 K1600x2-SSSE3-u2 K1600x4-AVX2-u12"/>

    <!-- Same as above, but using a 32-bit implementation and not exploiting any parallelism. -->
    <target name="libK12-32bits.a" inherits="KangarooTwelve K1600-plain-32bits-inplace"/>

    <!-- Type "make FIPS202-opt64.pack" to get a tarball with the sources needed to compile the FIPS 202 functions generically optimized for 64-bit platforms. -->
    <target name="FIPS202-opt64" inherits="FIPS202 K1600-plain-64bits-ua"/>

    <!-- Type "make MyUnitTests" to build an executable that runs the unit tests on a restricted set of functionality.
    In this example, the functionality is KangarooTwelve, with AVX2 code.
    -->
    <target name="MyUnitTests" inherits="KangarooTwelve K1600-AVX2 K1600x2-SSSE3-u2 K1600x4-AVX2-u12 UT"/>

    <!-- Type "make MyBenchmarks" to build an executable that benchmarks a restricted set of functionality.
    In this example, the functionality is Xoofff, with AVX2 code.
    -->
    <target name="MyBenchmarks" inherits="Xoofff Xoodoo-SSE2 Xoodoox4-SSSE3 Xoodoox8-AVX2 BM"/>

    <!-- Type "make libK12-AVX512.dylib" to build a dynamic library for macOS with KangarooTwelve with AVX512 code. -->
    <target name="libK12-AVX512.dylib" inherits="KangarooTwelve K1600-AVX512 K1600x2-AVX512-u12 K1600x4-AVX512-u12 K1600x8-AVX512-u12"/>

</group>