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.
Before you convert
Section titled “Before you convert”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.
-SNAPSHOTversions and the local repository (~/.m2/repository); see Dependencies.- Options for
javac, such as-Xlintor an annotation processor’s-Aoptions; see Compiling. - Publishing to Maven Central; see Publishing.
Rough edges
Section titled “Rough edges”| 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 initializationFor 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.
Windows-specific limitations.
Section titled “Windows-specific limitations.”- 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 -wandfabr run -wstop 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 afabr runof 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 apatchedtarget 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
scriptneeds a POSIX shell onPATH, such as theshGit for Windows installs; Windows has none of its own. SetSHELL = @host:'C:/Program Files/Git/usr/bin/sh.exe';to name one that isn’t onPATH.
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).