The make-like build tool that lives in your
package.json
.
mkjson [options]... [targets]...
-B
,--force
: Unconditionally make all targets.--log-level [err | info | verbose | debug]
: Set the log level.-V
,--version
: Print the version number.
mkjson is a make-like build tool but without shell syntax. With mkjson you can use familiar makefile
setups with great
efficiency, without worrying about weird shell interpretation issues.
mkjson recursively searches for any one of five files in the current directory and any of its parent directories in the given order;
makefile.js
makefile.json
makefile.json5
makefile
Makefile
package.json
Note: JSON5 is supported. Even if
package.json
doesn't support json5, it is valid frommkjson
's perspective.
if any are found in any parent directory, it is considered the project's makefile
. Alternatively, one can be
explicitely specified using the --makefile
flag.
All targets must be placed inside the targets
section in the file regardless of its name.
{
"name": "myproject",
// ...
"targets": {
// ...
}
}
Targets are the names of files or build steps. These are any key in the targets
map in the makefile. They may
represent one or multiple files on disk, or a generic name for a phony target, such as clean
.
A rule is the list of properties defined on the target key. These include its dependencies, run steps and other options.
A rule's build step is executed if any of the following conditions are met:
- The
--force
(-B) option is present - The rule is
phony
- Any of the target's dependencies were updated
- If the dependency represents a file on disk, the target and dependency's modification times are compared. If the dependency's is greater (the dependency was modified more recently than the target), the target is rebuilt.
- If the dependency represents a target, the steps listed above are run recursively.
A target may define any combination of the following properties:
dependencies
: Defines a list of targets which must be updated before the build step continuesorderOnly
: Dependencies which are specified purely to retain order. See GNU make order-onlyrun
:- If string: run as command as build step
- If array of strings: run each string as command separately
- If anything else: Error
parallel
: Whether therun
steps should be run in parallelisolate
: Whether eachrun
step should be run in its own shellcwd
: The directory from which therun
steps are executedenv
: A list of environment variables to pass to therun
steps.
Variables are useful for holding and retrieving information from the environment. This is useful if for instance you wish to allow compilers to be hot-plugged or to easily swap interpreter versions etc.
Variables are declared in the makefile's env
section. Keys are exported to environment variables, with values set to
the stdout
stream when its value is run as a child process.
If the value is an array, each is interpreted as a child process and each's stdout is piped into the next's stdin, where the last stdout is captured and used as the value. Analogous to UNIX shell's piping system.
{
"name": "myproject",
// ...
"env": {
"value1": [
"cat package.json",
"jq -r '.'"
]
},
"targets": {
"test": {
"phony": true,
"run": "echo $value1"
}
}
}
Makefile
s just tell mkjson what to do when a condition is met, this is usually in the form of some sort of command or
CLI invocation, however it is also possible to define targets dynamically using regular JavaScript files. This is useful
if your build step requires interacting with tools in non-standard ways, or if you require more fine-grained control
over how your build step is executed.
import target, {shell} from "mkjson";
target("test", shell('echo hi'));
and run it as normal
$ mkjson --makefile ./makefile.js test
Note the use of the --makefile
flag requires the .js
extension to work.
Note: Scripted makefiles can be blocked using the
--no-script
flag.