Skip to content

Known limitations

Fabr builds, tests and runs real JavaScript, TypeScript and Java projects, itself included, but it is under active development. Before you convert a project, check it against the first section of this page: it lists what a project coming from npm, Maven or Gradle may rely on that fabr can’t do yet, each entry linking to the page with the details. The second section lists the places where fabr’s present behaviour falls short of what it intends, with a workaround for each.

Your project can’t be converted as it stands if it relies on any of these.

JavaScript and TypeScript

  • PostCSS plugins other than autoprefixer, so no Tailwind CSS, and no Less or Stylus; see Stylesheets.
  • A registry package that requires one of its own dependencies by a git or tarball URL. Fabr can’t resolve such a requirement; see Dependencies.

Java

  • Exclusions of your own, and relocations; see Dependencies.
  • -SNAPSHOT versions and the local repository (~/.m2/repository); see Dependencies.
  • Options for javac, such as -Xlint or an annotation processor’s -A options; see Compiling.
  • Publishing to Maven Central; see Publishing.
Limitation Effect
Programs a shell script starts are not tracked A different version of a program a script runs can change results without fabr noticing.
Optional dependencies required as * are dropped Such a dependency is missing, with no warning.
No lock between fabr processes Two builds at once may each do the same work; deleting the cache under fabr run removes the running program.
A default import can be read too early in an import cycle In ES-module output, a cycle that reads a package’s default import before its module has started running throws a ReferenceError.
On Windows, processes, file modes and links fall short A step’s leftover processes outlive it; executable modes are lost; incremental builds can need Developer Mode.

Programs a shell script starts are not tracked

Section titled “Programs a shell script starts are not tracked”

Fabr intends a build to depend only on its declared inputs. A script target runs under your machine’s /bin/sh (on Windows, the sh on PATH), which fabr identifies by its contents, as it does any program on your machine. The programs the script starts by name are the exception: fabr records nothing about them.

So a different version of a program a script runs can change a result without invalidating the cache. Fabr reuses results built with the old one.

Workaround: write the step as a js_script where you can, so that it runs on the Node.js release NODE names, or name each program as a command of its own (@host:protoc). Otherwise, keep the programs scripts use the same on machines that should produce the same results, and delete the cache after changing them.

A default import of a package can be read too early in an import cycle

Section titled “A default import of a package can be read too early in an import cycle”

In ES-module output, fabr binds a package’s default import through a const at the top of the importing module. A const has no value until its module starts running. So when two of your modules import each other and one calls into the other while it is still loading, a default import read in that call throws:

ReferenceError: Cannot access 'DateTime' before initialization

For example, a.ts imports DateTime from a package and then imports b.ts, and b.ts calls a function of a.ts at its top level that uses DateTime. An import binding has its value as soon as its package has loaded, and a.ts loads the package before b.ts, so with tsc’s output that read would not throw.

Workaround: break the cycle, or move the call out of the top level of b.ts, for example into a function that runs after loading.

Optional npm dependencies required only as * are left out silently

Section titled “Optional npm dependencies required only as * are left out silently”

An optional dependency that packages require only as * (for example fsevents: "*") has no version that can be selected, so fabr leaves it out, currently without a warning.

Workaround: declare the dependency yourself with a version.

Concurrent fabr processes duplicate work rather than sharing it

Section titled “Concurrent fabr processes duplicate work rather than sharing it”

Within one fabr process, each piece of work is done once, however many targets need it. Between processes there is no such coordination: two fabr runs at the same time that both need something neither has built will each build it.

This costs time, not correctness. Each process works in a directory of its own and adds a result to the cache in a single step, so two runs can’t corrupt an entry between them.

Workaround: none is needed for correctness. To avoid the repeated work, don’t start two builds of the same unbuilt change at once, for example in two worktrees of one branch. Builds of different changes, or of one already built, share the cache as usual.

Relatedly, fabr run installs the program it runs in the cache, and keeps the install there to reuse on the next run, so deleting the cache while fabr run or fabr run -w is running deletes the files of the program it is running. Stop the program first.

  • A process a build step leaves running outlives the step. On macOS and Linux, fabr stops everything a step started when the step ends. On Windows it can stop a step’s processes only while the step’s own process is still running. Whatever is left after it exits keeps running until fabr exits, and if fabr itself is ended outright (from Task Manager, say), only the processes fabr started directly stop.
  • fabr build -w and fabr run -w stop cleanly only through Ctrl-C at the console they run in, or when a program that started fabr with a Node.js IPC channel closes it. Windows can’t send a process any other request to stop, only end it outright, which skips fabr’s clean-up: for example, the container a fabr run of an image started is left running.
  • Files have no executable mode. A file fabr reads from disk on Windows, such as a build step’s output or a bin/ script, has no executable bit, so a package or archive built there doesn’t mark it executable, and a patched target loses the mode a patch gives a file.
  • Incremental builds need the right to make symbolic links. Fabr links each build’s record to its result. Without Developer Mode, or the right to create symbolic links granted another way, that link can’t be made, so every build of a step starts afresh.
  • A script needs a POSIX shell on PATH, such as the sh Git for Windows installs; Windows has none of its own. Set SHELL = @host:'C:/Program Files/Git/usr/bin/sh.exe'; to name one that isn’t on PATH.

Workaround: for the first two, stop leftover processes from Task Manager. For executable modes, build packages you publish on macOS or Linux. For incremental builds, turn on Developer Mode (Settings › System › For developers).