README.md (7952B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Manifest 22 23 > Load a manifest for compiling source files. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var manifest = require( '@stdlib/utils/library-manifest' ); 41 ``` 42 43 #### manifest( filepath, conditions\[, options] ) 44 45 Loads a manifest for compiling source files. 46 47 ```javascript 48 var conditions = { 49 'os': 'linux' 50 }; 51 52 var conf = manifest( './examples/manifest.json', conditions ); 53 // returns <Object> 54 ``` 55 56 The function accepts the following `options`: 57 58 - **basedir**: base directory from which to search for dependencies. Default: current working directory. 59 - **paths**: path convention. Must be either `'win32'`, `'mixed'`, or `'posix'`. Default: based on host platform. 60 61 The default search directory is the current working directory of the calling process. To specify an alternative search directory, set the `basedir` option. 62 63 ```javascript 64 var conditions = { 65 'os': 'linux' 66 }; 67 68 var opts = { 69 'basedir': __dirname 70 }; 71 72 var conf = manifest( './examples/manifest.json', conditions, opts ); 73 // returns <Object> 74 ``` 75 76 </section> 77 78 <!-- /.usage --> 79 80 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 81 82 <section class="notes"> 83 84 ## Notes 85 86 - A _manifest_ is a [JSON][json] file having the following fields: 87 88 - **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. 89 90 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. 91 92 - **fields**: an object `array` where each `object` has the following fields: 93 94 - **field**: key name corresponding to a field in **confs**. 95 - **resolve**: `boolean` indicating whether to resolve field values as file paths. If `true`, all field values are resolved relative to the manifest file. 96 - **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. 97 98 - **confs**: an object `array` where each `object` corresponds to a manifest configuration. Each `object` has the following fields: 99 100 - **src**: `array` of source files. 101 - **include**: `array` of include directories. 102 - **libraries**: `array` of linked library dependencies. 103 - **libpath**: `array` of linked library paths. 104 - **dependencies**: `array` of package dependencies containing source files. 105 106 An example _manifest_: 107 108 ```text 109 { 110 "options": { 111 "os": "linux" 112 }, 113 "fields": [ 114 { 115 "field": "src", 116 "resolve": true, 117 "relative": true 118 }, 119 { 120 "field": "include", 121 "resolve": true, 122 "relative": false 123 }, 124 { 125 "field": "libraries", 126 "resolve": false, 127 "relative": false 128 }, 129 { 130 "field": "libpath", 131 "resolve": true, 132 "relative": false 133 } 134 ], 135 "confs": [ 136 { 137 "os": "linux", 138 "src": [ 139 "./src/foo_linux.f", 140 "./src/foo_linux.c" 141 ], 142 "include": [ 143 "./include" 144 ], 145 "libraries": [], 146 "libpath": [], 147 "dependencies": [ 148 "@stdlib/blas/base/daxpy", 149 "@stdlib/blas/base/dasum", 150 "@stdlib/blas/base/dcopy" 151 ] 152 } 153 ] 154 } 155 ``` 156 157 - The function recursively walks the manifest dependency tree to resolve **all** source files, libraries, library paths, and include directories. 158 159 - 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. 160 161 - 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. 162 163 - If no fields in a `conditions` object have corresponding fields in a manifest's options, the function returns a manifest's default configuration. 164 165 </section> 166 167 <!-- /.notes --> 168 169 <!-- Package usage examples. --> 170 171 <section class="examples"> 172 173 ## Examples 174 175 <!-- eslint no-undef: "error" --> 176 177 ```javascript 178 var join = require( 'path' ).join; 179 var manifest = require( '@stdlib/utils/library-manifest' ); 180 181 // Resolve the absolute path of the manifest JSON file: 182 var fpath = join( __dirname, 'examples', 'manifest.json' ); 183 184 // Specify conditions for determining which configuration to load: 185 var conditions = { 186 'os': 'mac' 187 }; 188 189 // Specify options: 190 var opts = { 191 'basedir': __dirname 192 }; 193 194 // Load a manifest configuration: 195 var conf = manifest( fpath, conditions, opts ); 196 console.dir( conf ); 197 ``` 198 199 </section> 200 201 <!-- /.examples --> 202 203 <!-- Section for describing a command-line interface. --> 204 205 * * * 206 207 <section class="cli"> 208 209 ## CLI 210 211 <!-- CLI usage documentation. --> 212 213 <section class="usage"> 214 215 ### Usage 216 217 ```text 218 Usage: library-manifest [options] <filepath> [-- --<condition>=value ...] 219 220 Options: 221 222 -h, --help Print this message. 223 -V, --version Print the package version. 224 --dir basedir Base search directory. 225 --paths convention Path convention. 226 ``` 227 228 </section> 229 230 <!-- /.usage --> 231 232 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 233 234 <section class="notes"> 235 236 ### Notes 237 238 - Use command-line flags to specify conditions by placing them after a `--` separator. 239 240 </section> 241 242 <!-- /.notes --> 243 244 <!-- CLI usage examples. --> 245 246 <section class="examples"> 247 248 ### Examples 249 250 ```bash 251 $ library-manifest ./examples/manifest.json -- --os mac 252 ``` 253 254 </section> 255 256 <!-- /.examples --> 257 258 </section> 259 260 <!-- /.cli --> 261 262 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 263 264 <section class="references"> 265 266 </section> 267 268 <!-- /.references --> 269 270 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 271 272 <section class="links"> 273 274 [json]: http://www.json.org/ 275 276 </section> 277 278 <!-- /.links -->