Manifest

Load a manifest for compiling source files.

Usage

var manifest = require( '@stdlib/utils/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/utils/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