Creating Simics packages

Simics packages are created using the script bin/create-packages. This scripts takes a package specification file as input, and assembles files from the local filesystem into a Simics package.

Package specification files

A package specification file is a JSON file. A formal JSON validation scheme for this file is available in the Simics base package, in the path scripts/package-specs-schema.json.

The file describes a single object (i.e., dict in Python) on top level. The object maps host-qualified package names, like "Simics-Base-linux64", to package specifications, where a package specification is an object with string keys.

Required properties of a package specification

package-name (string)

Name identifier of the package, used for the install directory name. The naming convention is Camel-Kebab-Case. e.g. "Simics-Base" or "QSP".

package-number (integer or null)

Package number. Must be globally unique. If null, the package cannot be created; this can be useful for defining quasi-packages that never should be shipped.

name (string)

Name as a string, used e.g. for titles in UIs and documents. Often package-name with dashes replaced with spaces.

description (string)

One-line description of the package. Can be the empty string.

host (string)

The host OS this package can be installed on. Must be "linux64" or "win64".

version (string)

Version, typically on the form X.Y.Z or X.Y.preZ where X, Y and Z are integers.

build-id (integer)

A number that should increase monotonically on every release. This number has no technical significance for the package; in this context it is mainly useful as a hint to the end-user to see which packages were released at the same time. There is no global naming convention; some vendors use timestamps, others use an integer that is incremented on every release.

build-id-namespace (string)

An identifier unique to a package vendor, identifying a naming scheme for the build-id property. The idea is that it makes sense to compare the build IDs of two packages only if the packages have the same build ID namespace.

confidentiality (string)

A string indicating confidentiality of the model. This can be used by package databases for restricting access to a package, e.g. in case the model specification is only accessible under a non-disclosure agreement. Publicly available models can use "Public".

Other values used in packages provided by Intel include "Intel Confidential" and "Intel Top Secret", but any string is permitted.

files (object)

Describes the files to be distributed in the package.

For each file in the package, the object maps the destination path, i.e. where within the installation the file should appear, to source path, i.e. the absolute path of file on the local filesystem. The destination path is a relative path, using / as directory separator and no . or .. component, whereas the source path is an absolute path using the host's path conventions. I.e., on Windows, backslashes may be used in the source path but not in the destination path.

If a destination path ends with /, it denotes a whole directory, and the destination is given by an object instead of a string. This notation is intended for cases when the exact contents of a directory cannot be determined by the time the package specification file is created.

The destination object has three entries:

source-directory (string)

Absolute path to a directory on the local filesystem where the files to be packages are located.

file-list (string)

Absolute path to a file on the local filesystem containing a complete list of files to be distributed in this directory. The file is in JSON format and contains a single list of strings, each one representing a file to be included under this directory. Each string is a /-separated relative path without . or .. path elements, and denote the location relative both to the source-directory and the destination path.

suffixes (list of strings)

The suffixes property lists what file endings may be present among files in file-list. It is often possible to know this in advance; if it is not, then passing [""] as the set of suffixes denotes that any filename may appear.

The purpose of suffixes is to allow a reliable way of extracting a complete list of files with a particular suffix from a package specification, before all file lists have been generated. This is particularly useful for extraction of reference documentation, which needs the set of .so or .dll files of a package, but the set of files produced by the reference manual itself is defined by a file list because its HTML file names are not known in advance. If this file list declares a set of suffixes that does not include .so or .dll files, then it is safe for the reference documentation extraction to not scan this file list.

Optional properties of package specification

type

Must be "addon", unless you are building the base package (which is not externally supported).

disabled (boolean)

Default false. Controls the default behaviour of the create-packages script, which is to create packages for all non-disabled packages.

Other commonly used properties

These properties are ignored by packaging scripts, but may be used by other tools.

make-targets (list of strings)

Defines make targets to build in order to create the files needed to create this package.

doc-title (string)

Title to use in reference manuals. Often identical to the name property.

Module cache

When Simics is installed on a network mount and the installation contains a large number of modules, then it can take a long time to start Simics because module scanning needs to examine a large number of files over the network. Package specific module caches provide a remedy to this problem, by collecting all module metadata of a package into one file.

The module cache file of a package is named host/lib/Package-Name.modcache, e.g., linux64/lib/Simics-Base.modcache. The script bin/create-modcache can be used to create this file. The script takes a package specification JSON file as argument, and by default creates .modcache files for all packages defined there matching the current host. It does so by inspecting the files property of all packages. For each package that distributes a modcache entry with the expected filename, it creates a modcache file on the path on the local filesystem where the specification expects to find it. The modcache is created by extracting module metadata from all module files distributed in the package.

Note that the module cache generation step needs to be done after all modules have been built. Furthermore, Simics blindly trusts the package-level module cache, so if a module is rebuilt after the modcache is generated, then any updated module metadata will be ignored. Therefore, modcache generation should normally only be done by packaging scripts.