Development utility.

This project uses make as its development utility. For an overview of make, see the make manual.

To view a list of available Makefile targets,

$ make help

To launch a REPL,

$ make repl

Annotating source code is a useful means for inlining action items and notes. For example,

// FIXME: don't release the zalgo!
function foo( cb ) {
    if ( bar ) {
        return asyncFcn( cb );
    }
    cb();
}

To retrieve source code annotations,

$ make notes

The following annotations are recognized:

• TODO: annotates a future task.
• FIXME: annotates a problem.
• HACK: annotates fragile/non-general solutions.
• WARNING: annotates possible pitfalls or gotchas.
• OPTIMIZE: annotates code which needs optimizing.
• NOTE: annotates questions, comments, or anything which does not fit under TODO/FIXME/HACK/WARNING/OPTIMIZE and should be brought to a reader's attention.

The Makefile exposes several targets (also used internally) for finding project files. For example, to list all project files, excluding node_modules, build, reports, and hidden directories,

$ make list-files

To filter based on a file name or pattern,

# List only README.md files...
$ make FILES_PATTERN=README.md list-files

To filter based on a file path,

# List all files in the is-nan utils directory...
$ make FILES_FILTER=".*/assert/is-nan/.*" list-files

Notes:

• Most filters should begin with .*/ and end with /.*, as a filter is used as a regular expression to test a file path.

• The *_PATTERN and *_FILTER environment variables map to -name and -regex options, respectively, for the find command. For certain types of operations, like regular expressions using | for alternative matches, you may need to use *_FILTER over *_PATTERN. For instance,

  # List all `R` test fixtures...
  $ make TESTS_FIXTURES_PATTERN=*.R
  
  # List all `R` and `Julia` test fixtures...
  $ make TESTS_FIXTURES_FILTER='.*/*\.(jl|R)' list-test-fixtures

The Makefile includes the following common recipes for listing different file types...

To list all source files, excluding examples, benchmarks, and tests,

$ make list-sources

To filter based on a file name or pattern,

# List only source files having the filename `index.js`...
$ make SOURCES_PATTERN=index.js list-sources

To filter based on a file path,

# List only source files found in a math directory...
$ make SOURCES_FILTER=".*/math/.*" list-sources

To list all test files,

$ make list-tests

To filter based on a file name or pattern,

# List only the main test files...
$ make TESTS_PATTERN=test.js list-tests

To filter based on a file path,

# List only test files in the fs directory...
$ make TESTS_FILTER=".*/fs/.*" list-tests

To list all test fixture files,

$ make list-tests-fixtures

To filter based on a file name or pattern,

# List only the Julia test fixtures...
$ make TESTS_FIXTURES_PATTERN=*.jl list-tests-fixtures

To filter based on a file path,

# List only test fixture files in the base math directory for special functions...
$ make TESTS_FIXTURES_FILTER=".*/math/special/.*" list-tests-fixtures

To list all benchmark files,

$ make list-benchmarks

To filter based on a file name or pattern,

# List only the main benchmark files...
$ make BENCHMARKS_PATTERN=benchmark.js list-benchmarks

To filter based on a file path,

# List only benchmark files for base special math functions...
$ make BENCHMARKS_FILTER=".*/math/base/special/.*" list-benchmarks

To list all examples files,

$ make list-examples

To filter based on a file name or pattern,

# List only those examples having a filename `index.js`...
$ make EXAMPLES_PATTERN=index.js list-examples

To filter based on a file path,

# List only the example files for special functions in the base math directory...
$ make EXAMPLES_FILTER=".*/math/base/special/.*" list-examples

To list all packages (as absolute paths),

$ make list-pkgs

To filter based on a file path,

# List only the special function packages in the base math directory...
$ make PACKAGES_FILTER=".*/math/base/special/.*" list-pkgs

To list all package names under the @stdlib scope,

$ make list-pkgs-names

To list all package names under a @stdlib descendant directory,

$ make SRC_DIR=./@stdlib/math/base list-pkgs-names

To run package examples,

$ make examples

To limit which examples are run, use the same environment variables recognized by list-examples.

# Only run the examples for special functions in the base math directory...
$ make EXAMPLES_FILTER=".*/math/base/special/.*" EXAMPLES_PATTERN=index.js examples

To run unit tests,

$ make test

To generate a test summary,

$ make test-summary

To limit which tests are run, use the same environment variables recognized by list-tests.

# Run only the main test file for base math utils...
$ make TESTS_FILTER=".*/math/base/utils/.*" TESTS_PATTERN=test.js test

# Run all blas tests...
$ make TESTS_FILTER=".*/math/base/blas/.*"  test-summary

To run unit tests against specific Node.js versions (assuming nvm is installed),

$ make test-node-versions

By default, tests are run against supported Node.js versions. To run against alternative versions, set the NODE_VERSIONS environment variable.

$ make NODE_VERSIONS='0.10 4 6' TESTS_FILTER=".*/fs/exists/.*" test-node-versions

To run units tests for project tools,

$ make tools-test

To limit which tests are run, use the same environment variables recognized by list-tests.

$ make tools-test TESTS_FILTER=".*/search/.*" TESTS_PATTERN=test.js

To generate a test coverage report,

$ make test-cov

To limit which tests are run, use the same environment variables recognized by list-tests.

# Generate a coverage report for base math utils...
$ make TESTS_FILTER=".*/math/base/utils/.*" test-cov

To generate a coverage report for project tools,

$ make tools-test-cov

To limit which tests are run, use the same environment variables recognized by list-tests.

$ make tools-test-cov TESTS_FILTER=".*/search/.*" TESTS_PATTERN=test.js

To view a generated report in a local web browser,

$ make view-cov

To run browser tests in a (headless) local web browser,

$ make test-browsers

To run and view the tests in a local web browser,

$ make view-browser-tests

To limit which tests are run, use the same environment variables recognized by list-tests.

# Run base math utils tests in a headless local web browser...
$ make TESTS_FILTER=".*/math/base/utils/.*" test-browsers

# Run @stdlib utils tests in a local web browser...
$ make TESTS_FILTER=".*/\@stdlib/utils/.*" test-view-browsers

To run benchmarks,

$ make benchmark

To limit which benchmarks are run, use the same environment variables recognized by list-benchmarks.

# Run only the benchmarks for base special math functions...
$ make BENCHMARKS_FILTER=".*/math/base/special/.*" BENCHMARKS_PATTERN=benchmark.js benchmark

To generate documentation from JSDoc source code comments,

$ make src-docs

To view the documentation in a local web browser,

$ make view-src-docs

To lint files, including tests, examples, filenames, package.json, and Markdown,

$ make SOURCES_FILTER=... TESTS_FILTER=... EXAMPLES_FILTER=... BENCHMARKS_FILTER=... MARKDOWN_FILTER=... lint

To lint only source files,

$ make SOURCES_FILTER=... lint-src

To lint only test files,

$ make TESTS_FILTER=... lint-tests

To lint only example files,

$ make EXAMPLES_FILTER=... lint-examples

To lint only benchmark files,

$ make BENCHMARKS_FILTER=... lint-benchmarks

To lint only Markdown files,

$ make MARKDOWN_FILTER=... lint-markdown

To lint only JavaScript files,

$ make SOURCES_FILTER=... TESTS_FILTER=... EXAMPLES_FILTER=... BENCHMARKS_FILTER=... lint-javascript

To lint filenames,

$ make lint-filenames

To lint package.json files,

$ make lint-pkg-json

To analyze code complexity,

$ make SOURCES_FILTER=... TESTS_FILTER=... EXAMPLES_FILTER=... complexity

To analyze only source files,

$ make SOURCES_FILTER=... complexity-src

To analyze only test files,

$ make TESTS_FILTER=... complexity-tests

To analyze only example files,

$ make EXAMPLES_FILTER=... complexity-examples

To analyze only benchmark files,

$ make BENCHMARKS_FILTER=... complexity-benchmarks

To analyze only JavaScript files,

$ make SOURCES_FILTER=... TESTS_FILTER=... EXAMPLES_FILTER=... complexity-javascript

To check whether dependencies are up-to-date,

$ make check-deps

To check licenses of installed package dependencies,

$ make check-licenses

To enable bash completion of Makefile targets, add

complete -W "\`find . ! \( -path \"*/node_modules/*\" -prune \) -and \( -name 'Makefile' -o -name '*.mk' \) | xargs grep '^.PHONY: ' | awk '{print $2}'\`" make

to your ~/.bash_profile or ~/.bashrc. Note that completion is not exhaustive, as the above only includes targets which have been explicitly declared phony targets

.PHONY: beep-boop

and does not include targets declared via variables. Excluded targets could be included by mining the Makefile database make -qp, but such inclusion has a performance cost and is unnecessary due to the predominant use of PHONY.