time-to-botec/squiggle/node_modules/@stdlib/utils/library-manifest/README.md

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