-
Notifications
You must be signed in to change notification settings - Fork 4
Floco Packages Modules
- option
floco
- description
- Scope used for configuring
floco
framework. - type
- submodule
- from
- <floco>/top/implementation.nix <floco>/top/interface.nix
- option
floco.fetcher
- description
- Abstract fetcher interface to be implemented by
floco.fetcher.*
members.
The attribute name used for the fetcher may be written to lockfiles so choose wisely.
- type
- module
- from
- <floco>/fetcher/interface.nix
- option
floco.fetcher.deserializeFetchInfo
- description
- Function which transforms serialized
fetchInfo
( an attrset or
string ) into its attrset form as specified by the
fetchInfo
submodule.
This routine should produce an exact replica of the original
record before it was serialized by serializeFetchInfo
.
This routine accepts two arguemnts.
The first is _file
indicating an absolute path the the file
being deserialized - this is useful for resolving relative paths.
The second is the serialized form of fetchInfo
.
See Also: serializeFetchInfo, lockFetchInfo
- type
- function that evaluates to a(n) function that evaluates to a(n) lazy attribute set of raw value
- from
- <floco>/fetcher/interface.nix
- option
floco.fetcher.fetchInfo
- description
- Submodule type representing arguments passed to fetch function in
order to produce a sourceInfo
record.
This is used to typecheck when parsing lockfiles.
- type
- optionType
- from
- <floco>/fetcher/interface.nix
- option
floco.fetcher.function
- description
- Function which performs the fetch.
This function will be passed a fetchInfo
record and must return
a sourceInfo
record which at a minimum must contain the field
outPath
as a member.
This function must NOT return a raw string.
- type
- raw value
- from
- <floco>/fetcher/interface.nix
- example
{
function = fetchInfo: { outPath = builtins.path fetchInfo; };
}
- option
floco.fetcher.lockFetchInfo
- description
- A function which fills missing arguments from an “impure”
fetchInfo
record to produce a “pure” fetchInfo
record.
This routine is used to create lockfiles during discovery phases.
- type
- function that evaluates to a(n) lazy attribute set of raw value
- from
- <floco>/fetcher/interface.nix
- example
{
lockFetchInfo = fetchInfo: let
outPath = builtins.path {
inherit (fetchInfo) name path filter recursive;
};
sourceInfo = builtins.fetchTree {
type = "path";
path = outPath;
};
in { sha256 = sourceInfo.narHash; } // fetchInfo;
}
- option
floco.fetcher.pure
- description
- Whether fetcher is restricted to pure evaluations.
- type
- boolean
- from
- <floco>/fetcher/interface.nix
- option
floco.fetcher.serializeFetchInfo
- description
- Function which transforms
fetchInfo
into a minimal value to be
written to a lockile.
The return value may be a string or attrset of values that are coercible to JSON and must not contain absolute filesystem paths.
This function’s output should produce an exact replica of
fetchInfo
when passed to deserializeFetchInfo
.
This routine accepts two arguemnts.
The first is _file
indicating an absolute path the the file
being serialized to - this is useful for creating relative paths.
The second is the deserialized form of fetchInfo
.
See Also: deserializeFetchInfo, lockFetchInfo
- type
- function that evaluates to a(n) function that evaluates to a(n) (string or attribute set of (null or string or signed integer or boolean))
- from
- <floco>/fetcher/interface.nix
- option
floco.fetchers
- description
- Fetcher abstractions associated with various forms of inputs and
evaluation rules.
- type
- attribute set of (
fetcher
submodule) - from
- <floco>/fetchers/implementation.nix <floco>/fetchers/interface.nix
- option
floco.fetchers.fetchTree_file
- description
-
builtins.fetchTree[file]
fetcher - type
- submodule
- from
- <floco>/fetchers/fetcher/fetchTree/file/implementation.nix <floco>/fetchers/fetcher/fetchTree/file/interface.nix
- option
floco.fetchers.fetchTree_git
- description
-
builtins.fetchTree[git]
fetcher - type
- submodule
- from
- <floco>/fetchers/fetcher/fetchTree/git/implementation.nix <floco>/fetchers/fetcher/fetchTree/git/interface.nix
- option
floco.fetchers.fetchTree_github
- description
-
builtins.fetchTree[github]
fetcher - type
- submodule
- from
- <floco>/fetchers/fetcher/fetchTree/github/implementation.nix <floco>/fetchers/fetcher/fetchTree/github/interface.nix
- option
floco.fetchers.fetchTree_tarball
- description
-
builtins.fetchTree[tarball]
fetcher - type
- submodule
- from
- <floco>/fetchers/fetcher/fetchTree/tarball/implementation.nix <floco>/fetchers/fetcher/fetchTree/tarball/interface.nix
- option
floco.fetchers.path
- description
-
builtins.path
fetcher - type
- submodule
- from
- <floco>/fetchers/path/implementation.nix <floco>/fetchers/path/interface.nix
- option
floco.fetchers.pure
- description
- Whether fetchers are restricted to pure evaluations.
Impure fetchers often autofill missing sha256
, narHash
, rev
,
and other fields which allow later runs to refetch
resources purely.
- type
- boolean
- from
- <floco>/fetchers/interface.nix
- option
floco.packages
- description
- Collection of built/prepared packages and modules.
- type
- attribute set of attribute set of (submodule)
- from
- <floco>/packages/implementation.nix <floco>/packages/interface.nix
- example
{
lodash = {
"4.17.21" = {
key = "lodash/4.17.21";
};
};
}
- option
floco.packages.<ident>.<version>.built
- description
- “Built” form of a package/module which is ready for distribution as a
tarball ( build
and prepublish
scripts must be run if defined ).
By default the dev
tree is used for this stage.
If no build is required then this option is an alias of source
.
XXX: If a build
script produces executable scripts you should NOT
patch shebangs yet - patching should be deferred to the
prepared
stage.
- type
- submodule
- from
- <floco>/package/targets/built/interface.nix
- option
floco.packages.<ident>.<version>.built.copyTree
- description
- Whether
node_modules/
tree should be copied into build area
instead of symlinked.
This may resolve issues with certain dependencies with non-compliant
implementations of resolve
such as webpack
or jest
.
- type
- boolean
- from
- <floco>/package/targets/built/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.built.dependsOnLint
- description
- Causes the
built
lifecycle stage to be blocked by successful
lint
checking ( requires lint
to be non-null ).
This is recommended for projects which are under active development.
If preferMultipleOutputDerivations
is enabled this is implemented
by making the lint
derivation an input of the built
derivation.
Otherwise this will cause a preBuild
phase to run lint
checks,
killing the builder if the check fails.
NOTE: if built
is an alias of source
, this causes either
installed
or prepared
to depend on lint
instead.
See Also: lint, install.dependsOnTest
- type
- boolean
- from
- <floco>/package/targets/built/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.built.enable
- description
- Whether to enable
built
target. - type
- boolean
- from
- <floco>/package/targets/built/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.built.override
- description
- Overrides applied to
stdenv.mkDerivation
invocation.
This option is a shorthand form of overrideAttrs
and it is an
error to set both options.
See Also: *.overrideAttrs
- type
- null or (attribute set of anything)
- from
- <floco>/package/targets/built/interface.nix
- example
{
preBuild = ''
echo "Howdy" >&2;
'';
}
- option
floco.packages.<ident>.<version>.built.overrideAttrs
- description
- Override function applied to
stdenv.mkDerivation
invocation.
This option is an advanced form of override
which allows prev
arguments to be referenced.
It is an error to set both options.
See Also: *.override
- type
- null or (function that evaluates to a(n) anything)
- from
- <floco>/package/targets/built/interface.nix
- example
{ pkgs, config, ... }: {
config.built.overrideAttrs = prev: {
nativeBuildInputs = prev.nativeBuildInputs ++ [
pkgs.typescript
];
};
}
- option
floco.packages.<ident>.<version>.built.package
- description
- Derivation which produces the
built
form of the package/module. - type
- package
- from
- <floco>/package/targets/built/interface.nix
- option
floco.packages.<ident>.<version>.built.scripts
- description
- Scripts that should be run during “build” process.
These scripts are run in the order listed, and if a script is
undefined in package.json
it is skipped.
- type
- list of string
- from
- <floco>/package/targets/built/interface.nix
- example
[
"build:part1"
"build:part2"
]
- option
floco.packages.<ident>.<version>.built.tree
- description
-
node_modules/
tree used for building. - type
- null or package
- from
- <floco>/package/targets/built/interface.nix
- option
floco.packages.<ident>.<version>.checkSystemSupport
- description
- A function that checks if
stdenv.hostPlatform
or asystem
pair can
support a package.
This uses translated sysInfo
records.
- type
- function that evaluates to a(n) boolean
- from
- <floco>/package/interface.nix
- example
checkSystemSupport = {
stdenv ? throw "checkSystemSupport: You must pass an arg"
, platform ? stdenv.hostPlatform
, system ? platform.system
}: ( builtins.match "x86_64-*" system ) != null
- option
floco.packages.<ident>.<version>.dist
- description
- Produce a distributable tarball suitable for publishing using the
built
form of a package.
This target should never be enabled for packages whose source
is
already a registry tarball ( those with ltype
of file
).
The contents of this tarball will attempt to unpatch scripts using the
original source
package’s contents - but if you produce any
executables during your build it is your responsibility to ensure that
they remain unpatched ( patching should be performed later during the
prepare
event instead ).
- type
- null or package
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.global
- description
- Globally installed form of a package which uses conventional
POSIX
installation prefixes such as lib/node_modules/
and bin/
.
Globally installed packages will carry their full runtime dependency
tree as a subdir, allowing executables to resolve any necessary modules,
and symlinks into other node_modules/
directories to behave as they
would with other Node.js package management tools.
NOTE: If a project has dependency cycles it may be necessary to enable
the option preferMultipleOutputDerivations
to allow any build
or
install
stages to run.
- type
- null or package
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.installDependsOnTest
- description
- Causes the
installed
lifecycle stage to be blocked by successful
test
checking ( required test
to be non-null ).
This is recommended for projects which are under active development.
If preferMultipleOutputDerivations
is enabled this is implemented by
making the test
derivation an input of the installed
derivation.
Otherwise this will cause a phase to run test
checks before install
events, killing the builder if the check fails.
NOTE: if installed
is an alias of built
, this causes either
prepared
to depend on test
instead.
See Also: test, buildDependsOnLint
- type
- boolean
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.installed
- description
- “Installed” form of a package/module which is ready consumption as a
module in a node_modules/
directory, or global installation for use
as a package.
This stage requires that any install
scripts have been run, which
conventionally means “run node-gyp
to perform system dependant
compilation or setup”.
By default the prod
tree is used for this stage.
If no install is required then this option is an alias of built
.
XXX: If an install
script produces executable scripts you should NOT
patch shebangs yet - patching should be deferred to the
prepared
stage.
- type
- submodule
- from
- <floco>/package/targets/installed/interface.nix
- option
floco.packages.<ident>.<version>.installed.copyTree
- description
- Whether
node_modules/
tree should be copied into install area
instead of symlinked.
This may resolve issues with certain dependencies with non-compliant
implementations of resolve
such as webpack
or jest
.
- type
- boolean
- from
- <floco>/package/targets/installed/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.installed.dependsOnLint
- description
- Causes the
installed
lifecycle stage to be blocked by successful
test
checking ( requires test
to be non-null ).
This is recommended for projects which are under active development.
If preferMultipleOutputDerivations
is enabled this is implemented
by making the test
derivation an input of the
installed
derivation.
Otherwise this will cause a preinstall
phase to run test
checks,
killing the installer if the check fails.
NOTE: if installed
is an alias of built
, this causes either
installed
or prepared
to depend on test
instead.
See Also: lint, built.dependsOnLint
- type
- boolean
- from
- <floco>/package/targets/installed/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.installed.enable
- description
- Whether to enable
installed
target. - type
- boolean
- from
- <floco>/package/targets/installed/interface.nix
- example
true
- option
floco.packages.<ident>.<version>.installed.override
- description
- Overrides applied to
stdenv.mkDerivation
invocation.
This option is a shorthand form of overrideAttrs
and it is an
error to set both options.
See Also: *.overrideAttrs
- type
- null or (attribute set of anything)
- from
- <floco>/package/targets/installed/interface.nix
- example
{
preinstall = ''
echo "Howdy" >&2;
'';
}
- option
floco.packages.<ident>.<version>.installed.overrideAttrs
- description
- Override function applied to
stdenv.mkDerivation
invocation.
This option is an advanced form of override
which allows prev
arguments to be referenced.
It is an error to set both options.
See Also: *.override
- type
- null or (function that evaluates to a(n) anything)
- from
- <floco>/package/targets/installed/interface.nix
- example
{ pkgs, config, ... }: {
config.installed.overrideAttrs = prev: {
nativeinstallInputs = prev.nativeinstallInputs ++ [
pkgs.typescript
];
};
}
- option
floco.packages.<ident>.<version>.installed.package
- description
- Derivation which produces the
installed
form of the
package/module.
- type
- package
- from
- <floco>/package/targets/installed/interface.nix
- option
floco.packages.<ident>.<version>.installed.scripts
- description
- Scripts that should be run during “install” process.
These scripts are run in the order listed, and if a script is
undefined in package.json
it is skipped.
- type
- list of string
- from
- <floco>/package/targets/installed/interface.nix
- example
[
"install:part1"
"install:part2"
]
- option
floco.packages.<ident>.<version>.installed.tree
- description
-
node_modules/
tree used for installing. - type
- null or package
- from
- <floco>/package/targets/installed/interface.nix
- option
floco.packages.<ident>.<version>.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- string
- from
- <floco>/package/interface.nix
- example
@floco/test/4.2.0
- option
floco.packages.<ident>.<version>.lint
- description
- Run lints against the
source
of a package.
By default this executes any lint
scripts defined in package.json
using the dev
tree.
As an optimization you may explicitly define treeInfo.lint
allowing
treeInfo.dev
to be reduced to the subset of dependencies required to
build, and treeInfo.lint
to be reduced to the subset of dependencies
required to run lints.
This approach is STRONGLY encouraged especially if you use jest
,
webpack
, or babel
since these packages’ all fail to properly
adhere to Node.js resolution specifications for symlinks, and often
require you to copy a massive pile of files into the sandbox.
This target should never be enabled for packages/modules whose source
was a distributed tarball ( those with ltype
or file
) since these
have already been linted as a part of their pre-release process.
See Also: test
- type
- null or package
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.pdef
- description
- Package’s declared metadata normalized as
pdef
submodule. - type
- submodule
- from
- <floco>/package/implementation.nix <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.pdef.binInfo
- description
- Indicates files or directories which should be prepared for use as
executable scripts.
- type
- submodule
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.binInfo.binDir
- description
- Relative path to a subdir from which all files should be prepared
as executables. Executable names will be defined as the basename of each file with any extensions stripped.
- type
- null or string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.binInfo.binPairs
- description
- Pairs of
{ <EXE-NAME> = <REL-PATH>; ... }
declarations mapping
exposed executables scripts to their associated sources.
- type
- attribute set of string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo
- description
- Information regarding dependency modules/packages.
This record is analogous to the various
package.json:.[dev|peer|optional|bundled]Dependencies[Meta]
fields.
These config settings do note necessarily dictate the contents of the
treeInfo
configs, which are used by builders, but may be used to provide
information needed to generate trees if they are not defined.
- type
- attribute set of (attribute set of boolean)
- from
- <floco>/pdef/depInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.bundled
- description
- Whether the dependency is distributed in registry tarballs alongside
the consumer.
This is sometimes used to include patched modules, but whenver possible
bundling should be avoided in favor of tooling like esbuild
or webpack
because the effect bundled dependencies have on resolution
is fraught.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.dev
- description
- Whether the dependency is required during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.pin
- description
- An exact version number or URI indicating the “resolved” form of a
dependency descriptor.
This will be used for treeInfo
formation, and is available for usage
by extensions to floco
.
- type
- null or string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.depInfo.<name>.runtime
- description
- Whether the dependency is required at runtime.
Other package management tools often refer to these as “production mode” dependencies.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.fetchInfo
- description
- Arguments passed to fetchers to produce a package/module’s source tree.
This field may be explicitly set to null
if sourceInfo
is
set instead.
The sourceInfo
produced by these arguments is primarily used for
“discovery” and “translation” of project metadata to create a build
plan, while floco.packages.*.*.source
is what is used by builds.
The default/fallback for floco.packages.*.*.source
bottoms out here
at fetchInfo
, but you may find that it is more convenient/optimal to
perform filtering of a source tree directly on
floco.packages.*.*.source
records rather than here to avoid
prematurely copying trees to the Nix store in the event that they aren’t
needed for the eventual build plan.
- type
- (lazy attribute set of anything) or string convertible to it
- from
- <floco>/pdef/implementation.nix <floco>/pdef/interface.nix
- option
floco.packages.<ident>.<version>.pdef.fsInfo
- description
- Indicates information about a package that must be scraped from its
source tree, rather than a conventional config file.
It is not recommended for users to manually fill these fields; rather we expect these to be informed by a cache or lockfile. You’re welcome to explicitly define them, but I don’t want to see anyone griping about these options in bug reports.
- type
- submodule
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.fsInfo.dir
- description
- Relative path from
sourceInfo.outPath
to the package’s root.
This field is analogous to a flake input’s dir
field, and is
used in combination with fetchInfo
in exactly the same way as
a flake input.
You should almost never need to set this field for distributed tarballs ( only if it contains bundled dependencies ).
While this field is useful for working with monorepos I strongly
recommend that you avoid abusing it.
Its use inherently causes rebuilds of all projects in associated
with a single sourceInfo
record for any change in the subtree.
It is much more efficient to split a subtree into multiple sources,
but I’ve left you enough rope to learn things the hard way if you
insist on doing so.
Consider yourself warned.
- type
- string
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.fsInfo.gypfile
- description
- Whether
binding.gyp
exists in the project root.
May be explicitly overridden by declarations in package.json
.
WARNING: You must not set this field based on ANY metadata pulled from a registry. There is a bug in NPM v8 that caused thousands of registry packuments and vinfo records to be poisoned, and in addition to that there is conflicting reporting rules for this field in POST requests by various package managers such that you should effectively disregard the value entirely.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.fsInfo.shrinkwrap
- description
- Whether
npm-shrinkwrap.json
exists in the project root.
This is distributed form of package-lock.json
which may be used to
install exact dependencies during global installation of packages.
For module/workspace installation this file takes precedence over
package-lock.json
if it exists.
The use of npm-shrinkwrap.json
is only recommended for executables.
NOTE: floco
does not use npm-shrinkwrap.json
at this time, so this
field exists as a stub.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.ident
- description
- Package identifier/name as found in
package.json:.name
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
@floco/foo
- option
floco.packages.<ident>.<version>.pdef.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- string
- from
- <floco>/pdef/interface.nix
- example
@floco/foo/4.2.0
- option
floco.packages.<ident>.<version>.pdef.lifecycle
- description
- Enables/disables phases executed when preparing a package/module for
consumption or installation.
Executing a phase when no associated script is defined is not necessarily harmful, but has a drastic impact on performance and may cause infinite recursion if dependency cycles exist among packages.
See Also: ltype
- type
- attribute set of boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.packages.<ident>.<version>.pdef.lifecycle.build
- description
- Whether a package or module requires build scripts to be run before
it is prepared for consumption.
This field should never be set to true when consuming registry tarballs even if they define build scripts, since they are distributed after being built by authors and maintainers.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.packages.<ident>.<version>.pdef.lifecycle.install
- description
- Whether a package or module requires
[pre|post]install
scripts or
node-gyp
compilation to be performed before a distributed tarball
is prepared for consumption.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.packages.<ident>.<version>.pdef.ltype
- description
- Package “lifecycle type”/”pacote source type”.
This option effects which lifecycle events may run when preparing a package/module for consumption or installation.
For example, the file
( distributed tarball ) lifecycle does not run
any scripts.[pre|post]build
phases or result in any devDependencies
being added to the build plan - since these packages will have been
“built” before distribution.
However, scripts.[pre|post]install
scripts ( generally node-gyp
compilation ) does run for the file
lifecycle.
This option is effectively a shorthand for setting lifecycle
defaults,
but may also used by some fetchers and scrapers.
See Also: lifecycle, fetchInfo
- type
- one of “file”, “link”, “dir”, “git”
- from
- <floco>/pdef/interface.nix
- option
floco.packages.<ident>.<version>.pdef.peerInfo
- description
- Set of propagated dependencies that consumers of this package/module
must provide at runtime.
Often peer dependencies are used to enforce interface alignment across a set of modules but do not necessarily imply that the requestor depends on the declared peer at build time or runtime - rather it states “my consumers depend on the declared peer as a side effect of their dependence on me”.
NOTE: For the purposes of treeInfo
and the construction of a
node_modules/
tree, if a module declares a peer then that peer must
be placed in a “sibling” or parent node_modules/
directory, and never
as a subdirectory of the requestor!
The “sibling” case is why the term “peer” is used, indicating that these
modules must be “peers” living in the same node_modules/
directory;
in practice a parent directory also works, but you get the idea.
- type
- attribute set of (submodule)
- from
- <floco>/pdef/peerInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.peerInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a peer dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.peerInfo.<name>.optional
- description
- Whether consumers are required to provide the declared peer.
Optional peer declarations are conventionally used to handle platform
or architecture dependant modules which are only required for certain
systems - in general this field should be interpreted as “this
peer dependency is required under certain conditions”.
Often these conditions are audited using postinstall
scripts, and as
an optimization it may be worthwhile to ignore those audits if their
conditions can be asserted in Nix ( for example if you know system
,
there’s no reason to use a derivation to run some JavaScript that probes
and audits cpu
and os
).
- type
- boolean
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.sourceInfo
- description
- Information about the source tree a package resides in.
This record is analogous to that returned by builtins.fetchTree
for
flake inputs.
Used in combination with fetchInfo
and fsInfo.dir
, these three
nuggets of metadata are isomorphic with a flake input.
However, unlike flake inputs, sourceInfo.outPath
may set to a derived
store path if and only if fetchInfo
is explicitly set to null
.
In this case fsInfo.dir
is still used to identify a pacakage/module’s
root directory where we will attempt to read package.json
( must exist ) and similar metadata files will be read from
( if they exist ).
In this case you may avoid IFD
by explicitly setting top level fields,
specifically lifecycle
, sysInfo
, binInfo
, and treeInfo
or
depInfo
which are required by builders.
Alternatively you may explicitly set metaFiles.{pjs,plock,plent,trees}
fields directly - but keep in mind that these fields are never
guaranteed to be stable and their schema may change at any time
( so set the top level ones unless you
- type
- attribute set of (boolean or signed integer or string)
- from
- <floco>/pdef/interface.nix
- option
floco.packages.<ident>.<version>.pdef.sourceInfo.outPath
- description
- A Nix Store path containing the unpacked source tree in which this
package/module resides. The package need not be at the root this path; but when the project root is a subdir the option `fsInfo.dir` must be set in order for `package.json` and other metadata to be translated.
- type
- path
- from
- <floco>/pdef/interface.nix
- option
floco.packages.<ident>.<version>.pdef.sysInfo
- description
- Indicates platform, arch, and Node.js version support.
- type
- submodule
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.sysInfo.cpu
- description
- List of supported CPU architectures.
The string "*"
indicates that all CPUs are supported.
- type
- list of (one of “*”, “x86_64”, “i686”, “aarch”, “aarch64”, “powerpc64le”, “mipsel”, “riscv64”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.sysInfo.engines
- description
- Indicates supported tooling versions.
- type
- attribute set of string
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.sysInfo.engines.node
- description
- Supported Node.js versions.
- type
- string
- from
- <floco>/pdef/sysInfo/interface.nix
- example
>=14
- option
floco.packages.<ident>.<version>.pdef.sysInfo.os
- description
- List of supported operating systems.
The string "*"
indicates that all operating systems
are supported.
- type
- list of (one of “*”, “darwin”, “freebsd”, “netbsd”, “linux”, “openbsd”, “sunprocess”, “win32”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.packages.<ident>.<version>.pdef.treeInfo
- description
-
node_modules/
trees used for various lifecycle events.
These declarations are analogous to the package.*
field found in
package-lock.json(v2/3)
files.
This means that these fields should describe both direct and indirect
dependencies for the full dependency graph.
Tree declarations are expected to be pairs of node_modules/
paths to
“keys” ( matching the key
field in its Nix declaration ).
In practice we expect users to explicitly define this field only for
targets which they actually intend to create installables from, and we
recommend using a package-lock.json(v2/3)
to fill these values.
- type
- null or (attribute set of (attribute set of boolean))
- from
- <floco>/pdef/treeInfo/interface.nix
- example
{
"node_modules/@foo/bar" = {
key = "@foo/bar/1.0.0";
dev = true;
# ...
};
"node_modules/@foo/bar/node_modules/baz" = {
key = "baz/4.2.0";
dev = false;
# ...
};
# ...
}
- option
floco.packages.<ident>.<version>.pdef.treeInfo.<name>.dev
- description
- Whether the dependency is required ONLY during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.treeInfo.<name>.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- null or string
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.treeInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.packages.<ident>.<version>.pdef.version
- description
- Package version as found in
package.json:.version
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
4.2.0
- option
floco.packages.<ident>.<version>.preferMultipleOutputDerivations
- description
- Whether builders should prefer preparing sources with a single multiple
output derivation vs. multiple single output derivations.
Setting this to false
is sometimes useful for breaking dependency
cycles for global
packages or to intentionally introduce additional
cache breakpoints in projects with excessively long build
or install
phases ( this may avoid rebuilds for certain types of changes to the
dependency graph ).
In general it is faster to use multiple output derivations, since most Node.js lifecycle stages execute relatively quickly, and splitting them requires a full sandbox to be created for each stage.
- type
- unspecified value
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.prepared
- description
- Fully prepared form of package/module tree making it ready for
consumption as either a globally installed package, or module under a
node_modules/
tree.
Generally this option is an alias of a previous stage; but this also
provides a useful opportunity to explicitly define additional
post-processing routines that don’t use default built
or installed
stage builders ( for example, setting executable bits or applying
shebang patches to scripts ).
- type
- package
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.source
- description
- Unpacked source tree used as the basis for package/module preparation.
It is strongly recommended that you use config.pdef.sourceInfo
here
unless you are intentionally applying patches, filters, or your package
resides in a subdir of sourceInfo
.
XXX: This tree should NOT patch shebangs yet, since this would deprive builders which produce distributable tarballs or otherwise “un-nixify” a module of an “unpatched” point of reference to work with.
- type
- package
- from
- <floco>/package/targets/source/interface.nix
- option
floco.packages.<ident>.<version>.test
- description
- Run tests against the
built
form of a package.
By default this executes any test
scripts defined in package.json
using the dev
tree.
As an optimization you may explicitly define treeInfo.test
allowing
treeInfo.dev
to be reduced to the subset of dependencies required to
build, and treeInfo.test
to be reduced to the subset of dependencies
required to run tests.
This approach is STRONGLY encouraged especially if you use jest
,
webpack
, or babel
since these packages’ all fail to properly
adhere to Node.js resolution specifications for symlinks, and often
require you to copy a massive pile of files into the sandbox.
This target should never be enabled for packages/modules whose source
was a distributed tarball ( those with ltype
or file
) since these
have already been tested as a part of their pre-release process.
See Also: lint
- type
- null or package
- from
- <floco>/package/interface.nix
- option
floco.packages.<ident>.<version>.trees
- description
- Stashes
node_modules/
trees used for lifecycle events.
These are used to populate defaults for lint.tree
, built.tree
,
install.tree
, test.tree
, etc.
- type
- attribute set of package
- from
- <floco>/package/trees/interface.nix
- option
floco.packages.<ident>.<version>.trees.dev
- description
-
node_modules/
default tree used for pre-distribution phases such
as build, lint, test, etc.
NOTE: The final tree used for a lifecycle event is set in the
<EVENT>.tree
option - this option is a commonly used as the
default value for those trees, or as a base to be modified.
- type
- null or package
- from
- <floco>/package/trees/interface.nix
- option
floco.packages.<ident>.<version>.trees.prod
- description
-
node_modules/
tree used for[pre|post]install
and “runtime” for
globally installed packages.
NOTE: The final tree used for a lifecycle event is set in the
<EVENT>.tree
option - this option is a commonly used as the
default value for those trees, or as a base to be modified.
- type
- null or package
- from
- <floco>/package/trees/interface.nix
- option
floco.packages.<ident>.<version>.trees.supported
- description
- A filtered form of
treeInfo
which drops unsupported
optional dependencies.
- type
- null or (attribute set of (attribute set of boolean))
- from
- <floco>/package/trees/interface.nix
- option
floco.packages.<ident>.<version>.trees.supported.<name>.dev
- description
- Whether the dependency is required ONLY during
pre-distribution phases. This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/package/trees/interface.nix
- option
floco.packages.<ident>.<version>.trees.supported.<name>.key
- description
- Unique key used to refer to this package in
tree
submodules
and other floco
configs, metadata, and structures.
- type
- string
- from
- <floco>/package/trees/interface.nix
- option
floco.pdef
- description
- Abstract record used to declare a package/module at a specific version.
This is a “deferred” module making it extensible. Its base interface must be implemented, but the implementations themselves may be swapped or overridden.
- type
- module
- from
- <floco>/pdef/deferred.nix
- option
floco.pdef.binInfo
- description
- Indicates files or directories which should be prepared for use as
executable scripts.
- type
- submodule
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdef.binInfo.binDir
- description
- Relative path to a subdir from which all files should be prepared
as executables. Executable names will be defined as the basename of each file with any extensions stripped.
- type
- null or string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdef.binInfo.binPairs
- description
- Pairs of
{ <EXE-NAME> = <REL-PATH>; ... }
declarations mapping
exposed executables scripts to their associated sources.
- type
- attribute set of string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdef.depInfo
- description
- Information regarding dependency modules/packages.
This record is analogous to the various
package.json:.[dev|peer|optional|bundled]Dependencies[Meta]
fields.
These config settings do note necessarily dictate the contents of the
treeInfo
configs, which are used by builders, but may be used to provide
information needed to generate trees if they are not defined.
- type
- attribute set of (attribute set of boolean)
- from
- <floco>/pdef/depInfo/interface.nix
- option
floco.pdef.depInfo.<name>.bundled
- description
- Whether the dependency is distributed in registry tarballs alongside
the consumer.
This is sometimes used to include patched modules, but whenver possible
bundling should be avoided in favor of tooling like esbuild
or webpack
because the effect bundled dependencies have on resolution
is fraught.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.depInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.depInfo.<name>.dev
- description
- Whether the dependency is required during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.depInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.depInfo.<name>.pin
- description
- An exact version number or URI indicating the “resolved” form of a
dependency descriptor.
This will be used for treeInfo
formation, and is available for usage
by extensions to floco
.
- type
- null or string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.depInfo.<name>.runtime
- description
- Whether the dependency is required at runtime.
Other package management tools often refer to these as “production mode” dependencies.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdef.fetchInfo
- description
- Arguments passed to fetchers to produce a package/module’s source tree.
This field may be explicitly set to null
if sourceInfo
is
set instead.
The sourceInfo
produced by these arguments is primarily used for
“discovery” and “translation” of project metadata to create a build
plan, while floco.packages.*.*.source
is what is used by builds.
The default/fallback for floco.packages.*.*.source
bottoms out here
at fetchInfo
, but you may find that it is more convenient/optimal to
perform filtering of a source tree directly on
floco.packages.*.*.source
records rather than here to avoid
prematurely copying trees to the Nix store in the event that they aren’t
needed for the eventual build plan.
- type
- unspecified value
- from
- <floco>/pdef/interface.nix
- option
floco.pdef.fsInfo
- description
- Indicates information about a package that must be scraped from its
source tree, rather than a conventional config file.
It is not recommended for users to manually fill these fields; rather we expect these to be informed by a cache or lockfile. You’re welcome to explicitly define them, but I don’t want to see anyone griping about these options in bug reports.
- type
- submodule
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdef.fsInfo.dir
- description
- Relative path from
sourceInfo.outPath
to the package’s root.
This field is analogous to a flake input’s dir
field, and is
used in combination with fetchInfo
in exactly the same way as
a flake input.
You should almost never need to set this field for distributed tarballs ( only if it contains bundled dependencies ).
While this field is useful for working with monorepos I strongly
recommend that you avoid abusing it.
Its use inherently causes rebuilds of all projects in associated
with a single sourceInfo
record for any change in the subtree.
It is much more efficient to split a subtree into multiple sources,
but I’ve left you enough rope to learn things the hard way if you
insist on doing so.
Consider yourself warned.
- type
- string
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdef.fsInfo.gypfile
- description
- Whether
binding.gyp
exists in the project root.
May be explicitly overridden by declarations in package.json
.
WARNING: You must not set this field based on ANY metadata pulled from a registry. There is a bug in NPM v8 that caused thousands of registry packuments and vinfo records to be poisoned, and in addition to that there is conflicting reporting rules for this field in POST requests by various package managers such that you should effectively disregard the value entirely.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdef.fsInfo.shrinkwrap
- description
- Whether
npm-shrinkwrap.json
exists in the project root.
This is distributed form of package-lock.json
which may be used to
install exact dependencies during global installation of packages.
For module/workspace installation this file takes precedence over
package-lock.json
if it exists.
The use of npm-shrinkwrap.json
is only recommended for executables.
NOTE: floco
does not use npm-shrinkwrap.json
at this time, so this
field exists as a stub.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdef.ident
- description
- Package identifier/name as found in
package.json:.name
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
@floco/foo
- option
floco.pdef.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- string
- from
- <floco>/pdef/interface.nix
- example
@floco/foo/4.2.0
- option
floco.pdef.lifecycle
- description
- Enables/disables phases executed when preparing a package/module for
consumption or installation.
Executing a phase when no associated script is defined is not necessarily harmful, but has a drastic impact on performance and may cause infinite recursion if dependency cycles exist among packages.
See Also: ltype
- type
- attribute set of boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdef.lifecycle.build
- description
- Whether a package or module requires build scripts to be run before
it is prepared for consumption.
This field should never be set to true when consuming registry tarballs even if they define build scripts, since they are distributed after being built by authors and maintainers.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdef.lifecycle.install
- description
- Whether a package or module requires
[pre|post]install
scripts or
node-gyp
compilation to be performed before a distributed tarball
is prepared for consumption.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdef.ltype
- description
- Package “lifecycle type”/”pacote source type”.
This option effects which lifecycle events may run when preparing a package/module for consumption or installation.
For example, the file
( distributed tarball ) lifecycle does not run
any scripts.[pre|post]build
phases or result in any devDependencies
being added to the build plan - since these packages will have been
“built” before distribution.
However, scripts.[pre|post]install
scripts ( generally node-gyp
compilation ) does run for the file
lifecycle.
This option is effectively a shorthand for setting lifecycle
defaults,
but may also used by some fetchers and scrapers.
See Also: lifecycle, fetchInfo
- type
- one of “file”, “link”, “dir”, “git”
- from
- <floco>/pdef/interface.nix
- option
floco.pdef.peerInfo
- description
- Set of propagated dependencies that consumers of this package/module
must provide at runtime.
Often peer dependencies are used to enforce interface alignment across a set of modules but do not necessarily imply that the requestor depends on the declared peer at build time or runtime - rather it states “my consumers depend on the declared peer as a side effect of their dependence on me”.
NOTE: For the purposes of treeInfo
and the construction of a
node_modules/
tree, if a module declares a peer then that peer must
be placed in a “sibling” or parent node_modules/
directory, and never
as a subdirectory of the requestor!
The “sibling” case is why the term “peer” is used, indicating that these
modules must be “peers” living in the same node_modules/
directory;
in practice a parent directory also works, but you get the idea.
- type
- attribute set of (submodule)
- from
- <floco>/pdef/peerInfo/interface.nix
- option
floco.pdef.peerInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a peer dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.pdef.peerInfo.<name>.optional
- description
- Whether consumers are required to provide the declared peer.
Optional peer declarations are conventionally used to handle platform
or architecture dependant modules which are only required for certain
systems - in general this field should be interpreted as “this
peer dependency is required under certain conditions”.
Often these conditions are audited using postinstall
scripts, and as
an optimization it may be worthwhile to ignore those audits if their
conditions can be asserted in Nix ( for example if you know system
,
there’s no reason to use a derivation to run some JavaScript that probes
and audits cpu
and os
).
- type
- boolean
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.pdef.sourceInfo
- description
- Information about the source tree a package resides in.
This record is analogous to that returned by builtins.fetchTree
for
flake inputs.
Used in combination with fetchInfo
and fsInfo.dir
, these three
nuggets of metadata are isomorphic with a flake input.
However, unlike flake inputs, sourceInfo.outPath
may set to a derived
store path if and only if fetchInfo
is explicitly set to null
.
In this case fsInfo.dir
is still used to identify a pacakage/module’s
root directory where we will attempt to read package.json
( must exist ) and similar metadata files will be read from
( if they exist ).
In this case you may avoid IFD
by explicitly setting top level fields,
specifically lifecycle
, sysInfo
, binInfo
, and treeInfo
or
depInfo
which are required by builders.
Alternatively you may explicitly set metaFiles.{pjs,plock,plent,trees}
fields directly - but keep in mind that these fields are never
guaranteed to be stable and their schema may change at any time
( so set the top level ones unless you
- type
- attribute set of (boolean or signed integer or string)
- from
- <floco>/pdef/interface.nix
- option
floco.pdef.sourceInfo.outPath
- description
- A Nix Store path containing the unpacked source tree in which this
package/module resides. The package need not be at the root this path; but when the project root is a subdir the option `fsInfo.dir` must be set in order for `package.json` and other metadata to be translated.
- type
- path
- from
- <floco>/pdef/interface.nix
- option
floco.pdef.sysInfo
- description
- Indicates platform, arch, and Node.js version support.
- type
- submodule
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdef.sysInfo.cpu
- description
- List of supported CPU architectures.
The string "*"
indicates that all CPUs are supported.
- type
- list of (one of “*”, “x86_64”, “i686”, “aarch”, “aarch64”, “powerpc64le”, “mipsel”, “riscv64”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdef.sysInfo.engines
- description
- Indicates supported tooling versions.
- type
- attribute set of string
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdef.sysInfo.engines.node
- description
- Supported Node.js versions.
- type
- string
- from
- <floco>/pdef/sysInfo/interface.nix
- example
>=14
- option
floco.pdef.sysInfo.os
- description
- List of supported operating systems.
The string "*"
indicates that all operating systems
are supported.
- type
- list of (one of “*”, “darwin”, “freebsd”, “netbsd”, “linux”, “openbsd”, “sunprocess”, “win32”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdef.treeInfo
- description
-
node_modules/
trees used for various lifecycle events.
These declarations are analogous to the package.*
field found in
package-lock.json(v2/3)
files.
This means that these fields should describe both direct and indirect
dependencies for the full dependency graph.
Tree declarations are expected to be pairs of node_modules/
paths to
“keys” ( matching the key
field in its Nix declaration ).
In practice we expect users to explicitly define this field only for
targets which they actually intend to create installables from, and we
recommend using a package-lock.json(v2/3)
to fill these values.
- type
- null or (attribute set of (attribute set of boolean))
- from
- <floco>/pdef/treeInfo/interface.nix
- example
{
"node_modules/@foo/bar" = {
key = "@foo/bar/1.0.0";
dev = true;
# ...
};
"node_modules/@foo/bar/node_modules/baz" = {
key = "baz/4.2.0";
dev = false;
# ...
};
# ...
}
- option
floco.pdef.treeInfo.<name>.dev
- description
- Whether the dependency is required ONLY during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdef.treeInfo.<name>.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- null or string
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdef.treeInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdef.version
- description
- Package version as found in
package.json:.version
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
4.2.0
- option
floco.pdefs
- description
- List of
pdef
metadata records for all known pacakges
and modules. These records are used to generate build recipes and build plans.
- type
- lazy attribute set of lazy attribute set of (submodule)
- from
- <floco>/pdefs/implementation.nix <floco>/pdefs/interface.nix
- example
{
acorn = {
"8.8.1" = {
binInfo = {
binPairs = {
acorn = "./bin/acorn";
};
};
fetchInfo = {
narHash = "sha256-W14mU7fhfZajYWDfzRxzSMexNSYKIg63yXSnM/vG0P8=";
type = "tarball";
url = "https://registry.npmjs.org/acorn/-/acorn-8.8.1.tgz";
};
key = "acorn/8.8.1";
ltype = "file";
treeInfo = { };
};
};
lodash = {
"4.17.21" = {
fetchInfo = {
narHash = "sha256-amyN064Yh6psvOfLgcpktd5dRNQStUYHHoIqiI6DMek=";
type = "tarball";
url = "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz";
};
ident = "lodash";
ltype = "file";
treeInfo = { };
version = "4.17.21";
};
};
}
- option
floco.pdefs.<ident>.<version>.binInfo
- description
- Indicates files or directories which should be prepared for use as
executable scripts.
- type
- submodule
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.binInfo.binDir
- description
- Relative path to a subdir from which all files should be prepared
as executables. Executable names will be defined as the basename of each file with any extensions stripped.
- type
- null or string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.binInfo.binPairs
- description
- Pairs of
{ <EXE-NAME> = <REL-PATH>; ... }
declarations mapping
exposed executables scripts to their associated sources.
- type
- attribute set of string
- from
- <floco>/pdef/binInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo
- description
- Information regarding dependency modules/packages.
This record is analogous to the various
package.json:.[dev|peer|optional|bundled]Dependencies[Meta]
fields.
These config settings do note necessarily dictate the contents of the
treeInfo
configs, which are used by builders, but may be used to provide
information needed to generate trees if they are not defined.
- type
- attribute set of (attribute set of boolean)
- from
- <floco>/pdef/depInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.bundled
- description
- Whether the dependency is distributed in registry tarballs alongside
the consumer.
This is sometimes used to include patched modules, but whenver possible
bundling should be avoided in favor of tooling like esbuild
or webpack
because the effect bundled dependencies have on resolution
is fraught.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.dev
- description
- Whether the dependency is required during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.pin
- description
- An exact version number or URI indicating the “resolved” form of a
dependency descriptor.
This will be used for treeInfo
formation, and is available for usage
by extensions to floco
.
- type
- null or string
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.depInfo.<name>.runtime
- description
- Whether the dependency is required at runtime.
Other package management tools often refer to these as “production mode” dependencies.
- type
- boolean
- from
- <floco>/pdef/depInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.fetchInfo
- description
- Arguments passed to fetchers to produce a package/module’s source tree.
This field may be explicitly set to null
if sourceInfo
is
set instead.
The sourceInfo
produced by these arguments is primarily used for
“discovery” and “translation” of project metadata to create a build
plan, while floco.packages.*.*.source
is what is used by builds.
The default/fallback for floco.packages.*.*.source
bottoms out here
at fetchInfo
, but you may find that it is more convenient/optimal to
perform filtering of a source tree directly on
floco.packages.*.*.source
records rather than here to avoid
prematurely copying trees to the Nix store in the event that they aren’t
needed for the eventual build plan.
- type
- (lazy attribute set of anything) or string convertible to it
- from
- <floco>/pdef/implementation.nix <floco>/pdef/interface.nix
- option
floco.pdefs.<ident>.<version>.fsInfo
- description
- Indicates information about a package that must be scraped from its
source tree, rather than a conventional config file.
It is not recommended for users to manually fill these fields; rather we expect these to be informed by a cache or lockfile. You’re welcome to explicitly define them, but I don’t want to see anyone griping about these options in bug reports.
- type
- submodule
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.fsInfo.dir
- description
- Relative path from
sourceInfo.outPath
to the package’s root.
This field is analogous to a flake input’s dir
field, and is
used in combination with fetchInfo
in exactly the same way as
a flake input.
You should almost never need to set this field for distributed tarballs ( only if it contains bundled dependencies ).
While this field is useful for working with monorepos I strongly
recommend that you avoid abusing it.
Its use inherently causes rebuilds of all projects in associated
with a single sourceInfo
record for any change in the subtree.
It is much more efficient to split a subtree into multiple sources,
but I’ve left you enough rope to learn things the hard way if you
insist on doing so.
Consider yourself warned.
- type
- string
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.fsInfo.gypfile
- description
- Whether
binding.gyp
exists in the project root.
May be explicitly overridden by declarations in package.json
.
WARNING: You must not set this field based on ANY metadata pulled from a registry. There is a bug in NPM v8 that caused thousands of registry packuments and vinfo records to be poisoned, and in addition to that there is conflicting reporting rules for this field in POST requests by various package managers such that you should effectively disregard the value entirely.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.fsInfo.shrinkwrap
- description
- Whether
npm-shrinkwrap.json
exists in the project root.
This is distributed form of package-lock.json
which may be used to
install exact dependencies during global installation of packages.
For module/workspace installation this file takes precedence over
package-lock.json
if it exists.
The use of npm-shrinkwrap.json
is only recommended for executables.
NOTE: floco
does not use npm-shrinkwrap.json
at this time, so this
field exists as a stub.
- type
- boolean
- from
- <floco>/pdef/fsInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.ident
- description
- Package identifier/name as found in
package.json:.name
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
@floco/foo
- option
floco.pdefs.<ident>.<version>.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- string
- from
- <floco>/pdef/interface.nix
- example
@floco/foo/4.2.0
- option
floco.pdefs.<ident>.<version>.lifecycle
- description
- Enables/disables phases executed when preparing a package/module for
consumption or installation.
Executing a phase when no associated script is defined is not necessarily harmful, but has a drastic impact on performance and may cause infinite recursion if dependency cycles exist among packages.
See Also: ltype
- type
- attribute set of boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdefs.<ident>.<version>.lifecycle.build
- description
- Whether a package or module requires build scripts to be run before
it is prepared for consumption.
This field should never be set to true when consuming registry tarballs even if they define build scripts, since they are distributed after being built by authors and maintainers.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdefs.<ident>.<version>.lifecycle.install
- description
- Whether a package or module requires
[pre|post]install
scripts or
node-gyp
compilation to be performed before a distributed tarball
is prepared for consumption.
- type
- boolean
- from
- <floco>/pdef/lifecycle/interface.nix
- option
floco.pdefs.<ident>.<version>.ltype
- description
- Package “lifecycle type”/”pacote source type”.
This option effects which lifecycle events may run when preparing a package/module for consumption or installation.
For example, the file
( distributed tarball ) lifecycle does not run
any scripts.[pre|post]build
phases or result in any devDependencies
being added to the build plan - since these packages will have been
“built” before distribution.
However, scripts.[pre|post]install
scripts ( generally node-gyp
compilation ) does run for the file
lifecycle.
This option is effectively a shorthand for setting lifecycle
defaults,
but may also used by some fetchers and scrapers.
See Also: lifecycle, fetchInfo
- type
- one of “file”, “link”, “dir”, “git”
- from
- <floco>/pdef/interface.nix
- option
floco.pdefs.<ident>.<version>.peerInfo
- description
- Set of propagated dependencies that consumers of this package/module
must provide at runtime.
Often peer dependencies are used to enforce interface alignment across a set of modules but do not necessarily imply that the requestor depends on the declared peer at build time or runtime - rather it states “my consumers depend on the declared peer as a side effect of their dependence on me”.
NOTE: For the purposes of treeInfo
and the construction of a
node_modules/
tree, if a module declares a peer then that peer must
be placed in a “sibling” or parent node_modules/
directory, and never
as a subdirectory of the requestor!
The “sibling” case is why the term “peer” is used, indicating that these
modules must be “peers” living in the same node_modules/
directory;
in practice a parent directory also works, but you get the idea.
- type
- attribute set of (submodule)
- from
- <floco>/pdef/peerInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.peerInfo.<name>.descriptor
- description
- Descriptor indicating version range or exact source required to satisfy
a peer dependency.
The value "*"
allows any version or source to be used, as long as it
has the same identifier ( name ).
- type
- string
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.peerInfo.<name>.optional
- description
- Whether consumers are required to provide the declared peer.
Optional peer declarations are conventionally used to handle platform
or architecture dependant modules which are only required for certain
systems - in general this field should be interpreted as “this
peer dependency is required under certain conditions”.
Often these conditions are audited using postinstall
scripts, and as
an optimization it may be worthwhile to ignore those audits if their
conditions can be asserted in Nix ( for example if you know system
,
there’s no reason to use a derivation to run some JavaScript that probes
and audits cpu
and os
).
- type
- boolean
- from
- <floco>/pdef/peerInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.sourceInfo
- description
- Information about the source tree a package resides in.
This record is analogous to that returned by builtins.fetchTree
for
flake inputs.
Used in combination with fetchInfo
and fsInfo.dir
, these three
nuggets of metadata are isomorphic with a flake input.
However, unlike flake inputs, sourceInfo.outPath
may set to a derived
store path if and only if fetchInfo
is explicitly set to null
.
In this case fsInfo.dir
is still used to identify a pacakage/module’s
root directory where we will attempt to read package.json
( must exist ) and similar metadata files will be read from
( if they exist ).
In this case you may avoid IFD
by explicitly setting top level fields,
specifically lifecycle
, sysInfo
, binInfo
, and treeInfo
or
depInfo
which are required by builders.
Alternatively you may explicitly set metaFiles.{pjs,plock,plent,trees}
fields directly - but keep in mind that these fields are never
guaranteed to be stable and their schema may change at any time
( so set the top level ones unless you
- type
- attribute set of (boolean or signed integer or string)
- from
- <floco>/pdef/interface.nix
- option
floco.pdefs.<ident>.<version>.sourceInfo.outPath
- description
- A Nix Store path containing the unpacked source tree in which this
package/module resides. The package need not be at the root this path; but when the project root is a subdir the option `fsInfo.dir` must be set in order for `package.json` and other metadata to be translated.
- type
- path
- from
- <floco>/pdef/interface.nix
- option
floco.pdefs.<ident>.<version>.sysInfo
- description
- Indicates platform, arch, and Node.js version support.
- type
- submodule
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.sysInfo.cpu
- description
- List of supported CPU architectures.
The string "*"
indicates that all CPUs are supported.
- type
- list of (one of “*”, “x86_64”, “i686”, “aarch”, “aarch64”, “powerpc64le”, “mipsel”, “riscv64”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.sysInfo.engines
- description
- Indicates supported tooling versions.
- type
- attribute set of string
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.sysInfo.engines.node
- description
- Supported Node.js versions.
- type
- string
- from
- <floco>/pdef/sysInfo/interface.nix
- example
>=14
- option
floco.pdefs.<ident>.<version>.sysInfo.os
- description
- List of supported operating systems.
The string "*"
indicates that all operating systems
are supported.
- type
- list of (one of “*”, “darwin”, “freebsd”, “netbsd”, “linux”, “openbsd”, “sunprocess”, “win32”, “unknown”)
- from
- <floco>/pdef/sysInfo/interface.nix
- option
floco.pdefs.<ident>.<version>.treeInfo
- description
-
node_modules/
trees used for various lifecycle events.
These declarations are analogous to the package.*
field found in
package-lock.json(v2/3)
files.
This means that these fields should describe both direct and indirect
dependencies for the full dependency graph.
Tree declarations are expected to be pairs of node_modules/
paths to
“keys” ( matching the key
field in its Nix declaration ).
In practice we expect users to explicitly define this field only for
targets which they actually intend to create installables from, and we
recommend using a package-lock.json(v2/3)
to fill these values.
- type
- null or (attribute set of (attribute set of boolean))
- from
- <floco>/pdef/treeInfo/interface.nix
- example
{
"node_modules/@foo/bar" = {
key = "@foo/bar/1.0.0";
dev = true;
# ...
};
"node_modules/@foo/bar/node_modules/baz" = {
key = "baz/4.2.0";
dev = false;
# ...
};
# ...
}
- option
floco.pdefs.<ident>.<version>.treeInfo.<name>.dev
- description
- Whether the dependency is required ONLY during pre-distribution phases.
This includes common tasks such as building, testing, and linting.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.treeInfo.<name>.key
- description
- Unique key used to refer to this package in
tree
submodules and other
floco
configs, metadata, and structures.
- type
- null or string
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.treeInfo.<name>.optional
- description
- Whether the dependency may be omitted from the
node_modules/
tree.
Conventionally this is used to mark dependencies which are only required
under certain conditions such as platform, architecture, or engines.
Generally optional dependencies carry sysInfo
conditionals, or
postinstall
scripts which must be allowed to fail without blocking
the build of the consumer.
- type
- boolean
- from
- <floco>/pdef/treeInfo/single.interface.nix
- option
floco.pdefs.<ident>.<version>.version
- description
- Package version as found in
package.json:.version
. - type
- string matching a regex pattern
- from
- <floco>/pdef/interface.nix
- example
4.2.0