chromeos_smart_card_connector/docs/building.md

Building the code

This document describes steps needed for compiling the code of the Smart Card Connector App and examples of how programs can communicate with the app.

Common building prerequisites

• OS: Linux.

  Building under a different *nix system, Mac OS or Windows should be possible too, though most probably will require more efforts.

• The following tools should be present in the system: bash, make, curl, sed, mktemp, realpath, xxd, autoconf (with the "autoconf-archive" package), flex (or lex), pkg-config.

• Python 3.x.

• git (version 2.2.1+ is recommended).

• OpenSSL (version 1.0+ is recommended).

• Xvfb.

• (for 64-bit Linux) 32-bit version of libstdc++.

  For example, on Ubuntu it's provided by the libstdc++6:i386 package.

• Java Runtime Environment 7.

• CMake (needed only in Emscripten builds).

In order to run the built apps, you will need either of these:

• a Chromebook with ChromeOS >= 48.

  This will provide the closest environment to the real world's one.

  However, the disadvantage of this option is the inconvenient way of doing short development iterations: each time the built apps will have to be somehow transferred to the Chromebook and installed onto it.

• a locally installed Chrome browser with version >= 48.

  This option will save time during development, allowing to install and run the apps easily on the local machine.

  For convenience, each app's Makefile provides a special run target that creates a temporary local Chrome profile and runs the browser with having the app installed and run into it. This allows to test the apps locally, without interfering with the real Chrome profile.

  One downside of this option is that the desktop Chrome does not provide all the APIs that are provided under ChromeOS. The most noticeable example is the chrome.certificateProvider API: it's only available under ChromeOS, so its usages in the apps will have to be stubbed out when executing locally.

  Another downside is that the desktop OS may require additional setup in order to allow Chrome (and, consequently, the apps being executed in it) to access the USB devices. Some instructions are given in the docs/running-on-desktop.md document.

Building

Follow these steps for performing the initial build:

1. Execute:

   env/initialize.sh
   

   It's enough to execute this command only once, after you have cloned the whole repository (unless you would like to update to the latest tools versions).

   This will download and install locally the following dependencies required for building the apps:

   • Emscripten SDK (see https://emscripten.org)
   • some Python 3 modules

2. Execute:

   source env/activate
   

   This command sets the environment variables required for enabling the use of the tools downloaded at step 1.

3. Execute:

   ./make-all.sh
   

   This builds the Connector App, the C++ Example App and the JS Example App and all the libraries shared between them.

After that, you can perform incremental building of either all of the apps (by running the command from step 3.) or of the single app you work on (by following its build instructions).

You should only make sure, however, that the environment definitions are always here - and, if not, use the command from step 2 for setting them up back.

Incremental builds

After you executed make-all.sh once, you can rebuild the project much faster with your local changes, simply by running make in the project's root directory.

A sample command for an incremental build in the WebAssembly mode:

make -j30

Debug and Release building modes

During the development process, it's useful to enable the extended levels of logging and (depending on the actual app) the more extensive debug assertions checks.

Switching to the Debug building mode can be performed by adjusting the CONFIG environment variable, i.e. by executing the following shell command before building the apps::

export CONFIG=Debug

This triggers a number of things, basically (for some additional details regarding concrete apps refer to their own documentation):

• For the compiled JavaScript code - enables the creation of the source map allowing to view the uncompiled code when debugging.

• For the JavaScript code built using the Closure library logging subsystem - selects more verbose logging level by default and enables printing extended details in the log messages (e.g. dumps of all parameters for some functions).

• For the C/C++ code - undefines the NDEBUG macro, which enables some extended debug assertion checks, more verbose logging level and enables printing extended details in the log messages (e.g. dumps of all parameters for some functions).

However, please ensure that the publicly released apps are always using the Release mode. Otherwise, the user's privacy may be harmed as the debug log messages may contain sensitive data.

The Release mode is the default building mode; you can switch to it back from the Debug build by adjusting the CONFIG environment variable, for example:

export CONFIG=Release

or simply:

unset CONFIG