Manifest

Load a manifest for compiling source files.

Usage

var manifest = require( '@stdlib/tools/library-manifest' );

manifest( filepath, conditions[, options] )

Loads a manifest for compiling source files.

var conditions = {
    'os': 'linux'
};

var conf = manifest( './examples/manifest.json', conditions );
// returns <Object>

The function accepts the following options:

  • basedir: base directory from which to search for dependencies. Default: current working directory.
  • paths: path convention. Must be either 'win32', 'mixed', or 'posix'. Default: based on host platform.

The default search directory is the current working directory of the calling process. To specify an alternative search directory, set the basedir option.

var conditions = {
    'os': 'linux'
};

var opts = {
    'basedir': __dirname
};

var conf = manifest( './examples/manifest.json', conditions, opts );
// returns <Object>

Notes

  • A manifest is a JSON file having the following fields:

    • options: an object containing key-value pairs. Each key corresponds to a field in confs and may be used to conditionally select a configuration. Each value corresponds to the key's default value. The value for each field in a provided conditions object which has a corresponding field in options overrides the default value.

      Option keys are akin to primary keys in relational databases, in the sense that they should be used to uniquely identify a particular configuration. While individual key values may be shared across configurations, each configuration should have a unique combination of key values. Furthermore, default option values considered as a unique set should identify one and only one default configuration.

    • fields: an object array where each object has the following fields:

      • field: key name corresponding to a field in confs.
      • resolve: boolean indicating whether to resolve field values as file paths. If true, all field values are resolved relative to the manifest file.
      • relative: boolean indicating whether to resolve field values as relative file paths. This field is only considered when a manifest is a root manifest. If true, all field values, including those originating from dependencies, are resolved as relative file paths relative the root manifest.
    • confs: an object array where each object corresponds to a manifest configuration. Each object has the following fields:

      • src: array of source files.
      • include: array of include directories.
      • libraries: array of linked library dependencies.
      • libpath: array of linked library paths.
      • dependencies: array of package dependencies containing source files.

    An example manifest:

    {
      "options": {
        "os": "linux"
      },
      "fields": [
        {
          "field": "src",
          "resolve": true,
          "relative": true
        },
        {
          "field": "include",
          "resolve": true,
          "relative": false
        },
        {
          "field": "libraries",
          "resolve": false,
          "relative": false
        },
        {
          "field": "libpath",
          "resolve": true,
          "relative": false
        }
      ],
      "confs": [
        {
          "os": "linux",
          "src": [
            "./src/foo_linux.f",
            "./src/foo_linux.c"
          ],
          "include": [
            "./include"
          ],
          "libraries": [],
          "libpath": [],
          "dependencies": [
            "@stdlib/blas/base/daxpy",
            "@stdlib/blas/base/dasum",
            "@stdlib/blas/base/dcopy"
          ]
        }
      ]
    }   
    
  • The function recursively walks the manifest dependency tree to resolve all source files, libraries, library paths, and include directories.

  • An input filepath may be either a relative or absolute file path. If provided a relative file path, a manifest is resolved relative to the base search directory.

  • If a conditions object contains fields which do not correspond to manifest options, those fields are ignored (i.e., the "extra" fields have no effect when filtering manifest configurations). This allows providing a conditions object containing fields which only apply to certain subsets of manifest dependencies.

  • If no fields in a conditions object have corresponding fields in a manifest's options, the function returns a manifest's default configuration.

Examples

var join = require( 'path' ).join;
var manifest = require( '@stdlib/tools/library-manifest' );

// Resolve the absolute path of the manifest JSON file:
var fpath = join( __dirname, 'examples', 'manifest.json' );

// Specify conditions for determining which configuration to load:
var conditions = {
    'os': 'mac'
};

// Specify options:
var opts = {
    'basedir': __dirname
};

// Load a manifest configuration:
var conf = manifest( fpath, conditions, opts );
console.dir( conf );

CLI

Usage

Usage: library-manifest [options] <filepath> [-- --<condition>=value ...]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --dir basedir         Base search directory.
         --paths convention    Path convention.

Notes

  • Use command-line flags to specify conditions by placing them after a -- separator.

Examples

$ library-manifest ./examples/manifest.json -- --os mac