1This file contains instructions to build and install the TSS libraries. 2 3# Dependencies 4To build and install the tpm2-tss software the following software packages 5are required. In many cases dependencies are platform specific and so the 6following sections describe them for the supported platforms. 7 8## GNU/Linux: 9* GNU Autoconf 10* GNU Autoconf Archive, version >= 2017.03.21 11* GNU Automake 12* GNU Libtool 13* C compiler 14* C library development libraries and header files 15* pkg-config 16* doxygen 17* OpenSSL development libraries and header files, or optionally libgcrypt 18* libcurl development libraries 19 20* Please note that with FAPI enabled, the only option for the crypto backend is 21 OpenSSL. If only ESAPI is enabled it can work with either openSSL or libgrcypt, 22 however libgcrypt-dev is required as a dependency for the configure script 23 because it uses the AM_PATH_LIBGCRYPT macro. 24 See https://github.com/tpm2-software/tpm2-tss/issues/1365 for more info. 25 26The following are dependencies only required when building test suites. 27* Integration test suite (see ./configure option --enable-integration): 28 - uthash development libraries and header files 29 - ps executable (usually in the procps package) 30 - ss executable (usually in the iproute2 package) 31 - tpm_server executable (from https://sourceforge.net/projects/ibmswtpm2/) 32* Unit test suite (see ./configure option --enable-unit): 33 - cmocka unit test framework, version >= 1.0 34* Code coverage analysis: 35 - lcov 36 37Most users will not need to install these dependencies. 38 39### Ubuntu 40``` 41$ sudo apt -y update 42$ sudo apt -y install \ 43 autoconf-archive \ 44 libcmocka0 \ 45 libcmocka-dev \ 46 procps \ 47 iproute2 \ 48 build-essential \ 49 git \ 50 pkg-config \ 51 gcc \ 52 libtool \ 53 automake \ 54 libssl-dev \ 55 uthash-dev \ 56 autoconf \ 57 doxygen \ 58 libjson-c-dev \ 59 libini-config-dev \ 60 libcurl-dev \ 61 libgcrypt-dev 62``` 63Note: In some Ubuntu versions, the lcov and autoconf-archive packages are incompatible with each other. It is recommended to download autoconf-archive directly from upstream and copy `ax_code_coverage.m4` and `ax_prog_doxygen.m4` to the `m4/` subdirectory of your tpm2-tss directory. 64 65### Fedora 66 67There is a package already, so the package build dependencies information can be 68used to make sure that the needed packages to compile from source are installed: 69 70``` 71$ sudo dnf builddep tpm2-tss 72``` 73 74## Windows 75Windows dlls built using the Clang/LLVM "Platform Toolset" are currently 76prototypes. We have only tested using Visual Studio 2017 with the Universal 77C Runtime (UCRT) version 10.0.16299.0. Building the type marshaling library 78(tss2-mu.dll) and the system API (tss2-sapi.dll) should be as simple as 79loading the tpm2-tss solution (tpm2-tss.sln) with a compatible and properly 80configured version of Visual Studio 2017 and pressing the 'build' button. 81 82### References 83Visual Studio 2017 with "Clang for Windows": https://blogs.msdn.microsoft.com/vcblog/2017/03/07/use-any-c-compiler-with-visual-studio/ 84Universal CRT overview & setup instructions: https://docs.microsoft.com/en-us/cpp/porting/upgrade-your-code-to-the-universal-crt 85 86# Building From Source 87## Bootstrapping the Build 88To configure the tpm2-tss source code first run the bootstrap script, which 89generates list of source files, and creates the configure script: 90``` 91$ ./bootstrap 92``` 93 94Any options specified to the bootstrap command are passed to `autoreconf(1)`. 95 96## Configuring the Build 97Then run the configure script, which generates the makefiles: 98``` 99$ ./configure 100``` 101 102### Custom `./configure` Options 103In many cases you'll need to provide the `./configure` script with additional 104information about your environment. Typically you'll either be telling the 105script about some location to install a component, or you'll be instructing 106the script to enable some additional feature or function. We'll cover each 107in turn. 108 109Invoking the configure script with the `--help` option will display 110all supported options. 111 112The default values for GNU installation directories are documented here: 113https://www.gnu.org/prep/standards/html_node/Directory-Variables.html 114 115### udev Rules 116The typical operation for the `tpm2-abrmd` is for it to communicate directly 117with the Linux TPM driver using `libtcti-device` from the TPM2.0-TSS project. 118This requires that the user account that's running the `tpm2-abrmd` have both 119read and write access to the TPM device node `/dev/tpm[0-9]`. But users could 120also access the TPM directly so the udev rule is installed by `tpm2-tss`. 121 122#### `--with-udevrulesdir` 123This requires that `udev` be instructed to set the owner and group for this 124device node when its created. We provide such a udev rule that is installed to 125`${libdir}/udev/rules.d`. If your distro stores these rules elsewhere you will 126need to tell the build about this location. 127 128Using Debian as an example we can instruct the build to install the udev 129rules in the right location with the following configure option: 130``` 131--with-udevrulesdir=/etc/udev/rules.d 132``` 133 134#### `--with-udevrulesprefix` 135It is common for Linux distros to prefix udev rules files with a numeric 136string (e.g. "70-"). This allows for the rules to be applied in a predictable 137order. This option allows for the name of the installed udev rules file to 138have a string prepended to the file name when it is installed. 139 140## Compiling the Libraries 141Then compile the code using make: 142``` 143$ make -j$(nproc) 144``` 145 146## Installing the Libraries 147Once you've built the tpm2-tss software it can be installed with: 148``` 149$ sudo make install 150``` 151 152This will install the libraries to a location determined at configure time. 153See the output of ./configure --help for the available options. Typically you 154won't need to do much more than provide an alternative --prefix option at 155configure time, and maybe DESTDIR at install time if you're packaging for a 156distro. 157 158# Post-install 159 160## udev 161Once you have this udev rule installed in the right place for your distro 162you'll need to instruct udev to reload its rules and apply the new rule. 163Typically this can be accomplished with the following command: 164``` 165$ sudo udevadm control --reload-rules && sudo udevadm trigger 166``` 167 168If this doesn't work on your distro please consult your distro's 169documentation for UDEVADM(8). 170 171## ldconfig 172 173It may be necessary to run ldconfig (as root) to update the run-time 174bindings before executing a program that links against libsapi or a TCTI 175library: 176``` 177$ sudo ldconfig 178``` 179 180## Building In A Container 181 182If you are having trouble installing the dependencies on your machine you can 183build in a container. 184 185``` 186$ docker build -t tpm2 . 187$ docker run --name temp tpm2 /bin/true 188$ docker cp temp:/tmp/tpm2-tss tpm2-tss 189$ docker rm temp 190``` 191 192tpm2-tss is now in your working directory and contains all the built files. 193 194To rebuild using your local changes mount your tpm2-tss directory as a volume. 195 196```console 197$ docker run --rm -ti -v $PWD:/tmp/tpm2-tss tpm2-tss \ 198 sh -c 'make -j$(nproc) check' 199``` 200 201## Doxygen Documentation 202 203To build Doxygen documentation files, first install package Doxygen. 204Then generate the documentation with: 205 206``` 207$ ./configure --enable-doxygen-doc 208$ make doxygen-doc 209``` 210 211The generated documentation will appear here: 212* doxygen-doc/html HTML format (start with file doxygen-doc/html/index.html) 213* doxygen-doc/rtf/refman.rtf RTF format 214