Library Support

This page should outline the idea of making (common) libraries available to Emscripten users.

Idea

Provide commonly used libraries at a centralized location, so additional external libraries might be build without having to patch their build system for Emscripten.

Prototype

Since Emscripten has not support for dynamic libraries and/or their file format a solution should not rely on the dynamic library infrastructure. On Debian systems installing a library usually is done via dpkg or apt tools. Arguments necessary for linking with a library are commonly provided by invoking pkg-config.

These mechanism could be adopted for Emscripten in a simplified manner. In contrast to common *nix systems, empkg-tools can work with multiple versions of a package in parallel.

empkg-get - a tool for downloading libraries working with Emscripten

empkg-get <package name> <package name> ...

1. Downloads the <package name>/versions file from https://github.com/abergmeier/emscripten-libs for every package.
2. Finds the highest/latest version.
3. Checks whether the directory EM_LIBS/sources/<package name>/<version> is available and warns for overwrite if it is.
4. On success downloads (and overwrites) the version to EM_LIBS/sources/<package name>/<version>.

empkg-build - a tool to build downloaded library sources

empkg-build [--download] <package name> <package name>

1. If --download argument is present, tries to invoke empkg-get first and fail if it fails.
2. If a valid build timestamp is found return successfully.
3. Invoke build commands in build attribute of versions file. A full build cycle has to take place (consisting e.g. of configure, make, make install). The installation directory to use is set as the environment variable EMSCRIPTEN_SYSTEM_ROOT.
4. If building succeeds, create new build timestamp file.

empkg-config - a tool for getting building/linking configuration of library

empkg-config [--cflags] [--libs] <package name> <package name>

1. Limits pkg-config to searching in EM_LIBS/system directory.
2. Passes all arguments to pkg-config and returns its output.

Format of versions

The versions file is a JSON version of the data needed to download and build the sources. Entries in the upper section are derived by the version sections.

ignore_archive_root may be set when an archive does not contain the source directly (but contains an intermediate root folder).

{ "maintainers"        : [ { "name" : "Alon Zakai",
                             "email": "azakai@mozilla.org"
                           }
  ],
  "build"              : [ "emconfigure ./configure",
                           "emmake make",
                           "emmake make install" ],
  "ignore_archive_root": true,
  "versions"           : [ { "version": "1.2.7",
                             "src"    : "https://github.com/madler/zlib/archive/v1.2.7.zip"
                           }
  ]
}

Build environment

The build environment emulates a default *nix environment. Notable differences:

• Current Emscripten path is added to PATH environment variable. Thus all em*-commands can be called unprefixed.
• All libraries have an isolated build and installation directory. This way multiple versions of libraries can coexist. The installation path (AKA prefix) can be found in EMSCRIPTEN_SYSTEM_ROOT environment variable.
• Search path for pkg-config is limited to paths of Emscripten libraries only (via setting PKG_CONFIG_LIBDIR). This way it should be save to use pkg-config, as long as the environment is not disregarded or PKG_CONFIG_LIBDIR overwritten.

Pro

• Less to no work for users
• Higher chances for pushing patches upstream
• Handles multiple versions of same library

Contra

• Might not fit every usage scenario
• Library has to be available via sourcecode
• Maintainance necessary