Floco Packages Modules

Floco Options Manual

`floco`

option: floco
description: Scope used for configuring floco framework.
type: submodule
from: <floco>/top/implementation.nix <floco>/top/interface.nix

`buildPlan`

option: floco.buildPlan
description: Functions and metadata associated with build planning.
type: submodule
from: <floco>/buildPlan/interface.nix

`deriveTreeInfo`

option: floco.buildPlan.deriveTreeInfo
description: Whether floco should attempt to derive <pdef>.treeInfo records from pinned <pdef>.depInfo.*.pin fields.

This option should not be enabled if the build plan contains dependency cycles, unless explicit treeInfo records have been provided forall cycle memebers.

type: boolean
from: <floco>/buildPlan/interface.nix

`fetcher`

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

`fetchers`

option: floco.fetchers
description: Fetcher abstractions associated with various forms of inputs and evaluation rules.
type: attribute set of (submodule)
from: <floco>/fetchers/implementation.nix <floco>/fetchers/interface.nix

`deserializeFetchInfo`

option: floco.fetchers.<name>.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

`fetchInfo`

option: floco.fetchers.<name>.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

`function`

option: floco.fetchers.<name>.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; };
}

`input`

option: floco.fetchers.<name>.input
description: String type representing a stringized form of fetchInfo.

This string is analogous to Nix flakes’ input.url strings.

type: optionType
from: <floco>/fetcher/interface.nix

`lockFetchInfo`

option: floco.fetchers.<name>.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;
}

`pure`

option: floco.fetchers.<name>.pure
description: Whether fetcher is restricted to pure evaluations.
type: boolean
from: <floco>/fetcher/interface.nix

`serializeFetchInfo`

option: floco.fetchers.<name>.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

`composed`

option: floco.fetchers.composed
description: Generic fetcher comprised of multiple sub-fetchers.
type: submodule
from: <floco>/fetchers/composed/implementation.nix <floco>/fetchers/composed/interface.nix

`fetchTarballDrv`

option: floco.fetchers.fetchTarballDrv
description: Derivation form of nixpgkgs.fetchzip.
type: submodule
from: <floco>/fetchers/fetcher/fetchTarballDrv/implementation.nix <floco>/fetchers/fetcher/fetchTarballDrv/interface.nix

`fetchTree_file`

option: floco.fetchers.fetchTree_file
description: builtins.fetchTree[file] args
type: submodule
from: <floco>/fetchers/fetcher/fetchTree/file/implementation.nix <floco>/fetchers/fetcher/fetchTree/file/interface.nix

`fetchTree_git`

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

`fetchTree_github`

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

`fetchTree_tarball`

option: floco.fetchers.fetchTree_tarball
description: builtins.fetchTree[tarball] args
type: submodule
from: <floco>/fetchers/fetcher/fetchTree/tarball/implementation.nix <floco>/fetchers/fetcher/fetchTree/tarball/interface.nix

`path`

option: floco.fetchers.path
description: builtins.path fetcher
type: submodule
from: <floco>/fetchers/path/implementation.nix <floco>/fetchers/path/interface.nix

`pure`

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

`packages`

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";
    };
  };
}

`built`

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

`copyTree`

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

`dependsOnLint`

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.

`enable`

option: floco.packages.<ident>.<version>.built.enable
description: Whether to enable the target.
type: boolean
from: <floco>/package/targets/built/interface.nix
example: true

`extraBuildInputs`

option: floco.packages.<ident>.<version>.built.extraBuildInputs
description: Additional buildInputs passed to the builder.

“Build Inputs” are packages/tools that are available at build time and respect cross-compilation/linking settings. These are conventionally libraries, headers, compilers, or linkers, and should not be confused with nativeBuildInputs which are better suited for utilities used only to drive builds ( such as make, coreutils, grep, etc ).

This is processed before overrides, and may be set multiple times across modules to create a concatenated list.

`extraNativeBuildInputs`

option: floco.packages.<ident>.<version>.built.extraNativeBuildInputs
description: Additional nativeBuildInputs passed to the builder.

“Native Build Inputs” are packages/tools that are available at build time that are insensitive to cross-compilation/linking settings. These are conventionally CLI tools such as make, coreutils, grep, etc that are required to drive a build, but don’t produce different outputs depending on the build, host, or target platform.

This is processed before overrides, and may be set multiple times across modules to create a concatenated list.

type: list of (package or path)
from: <floco>/package/targets/built/interface.nix
example

{ pkgs, ... }: {
  config.extraNativeBuildInputs = [pkgs.typescript];
}

`override`

option: floco.packages.<ident>.<version>.built.override
description: Overrides applied to stdenv.mkDerivation invocation.

This option is processed after extra* options, and before overrideAttrs.

`overrideAttrs`

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. The function is evaluated after extra* options, and after applying override to the orginal argument set.

`package`

option: floco.packages.<ident>.<version>.built.package
description: Derivation which produces the target.
type: package
from: <floco>/package/targets/built/interface.nix

`scripts`

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"
]

`tree`

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

`checkSystemSupport`

option: floco.packages.<ident>.<version>.checkSystemSupport
description: A function that checks if stdenv.hostPlatform or a system 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

`dist`

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

`global`

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

`installDependsOnTest`

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.

`installed`

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

`copyTree`

option: floco.packages.<ident>.<version>.installed.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/installed/interface.nix
example: true

`dependsOnTest`

option: floco.packages.<ident>.<version>.installed.dependsOnTest
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.

`enable`

option: floco.packages.<ident>.<version>.installed.enable
description: Whether to enable the target.
type: boolean
from: <floco>/package/targets/installed/interface.nix
example: true

`extraBuildInputs`

option: floco.packages.<ident>.<version>.installed.extraBuildInputs
description: Additional buildInputs passed to the builder.

“Build Inputs” are packages/tools that are available at build time and respect cross-compilation/linking settings. These are conventionally libraries, headers, compilers, or linkers, and should not be confused with nativeBuildInputs which are better suited for utilities used only to drive builds ( such as make, coreutils, grep, etc ).

This is processed before overrides, and may be set multiple times across modules to create a concatenated list.

`extraNativeBuildInputs`

option: floco.packages.<ident>.<version>.installed.extraNativeBuildInputs
description: Additional nativeBuildInputs passed to the builder.

“Native Build Inputs” are packages/tools that are available at build time that are insensitive to cross-compilation/linking settings. These are conventionally CLI tools such as make, coreutils, grep, etc that are required to drive a build, but don’t produce different outputs depending on the build, host, or target platform.

This is processed before overrides, and may be set multiple times across modules to create a concatenated list.

type: list of (package or path)
from: <floco>/package/targets/installed/interface.nix
example

{ pkgs, ... }: {
  config.extraNativeBuildInputs = [pkgs.typescript];
}

`override`

option: floco.packages.<ident>.<version>.installed.override
description: Overrides applied to stdenv.mkDerivation invocation.

This option is processed after extra* options, and before overrideAttrs.

`overrideAttrs`

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. The function is evaluated after extra* options, and after applying override to the orginal argument set.

`package`

option: floco.packages.<ident>.<version>.installed.package
description: Derivation which produces the target.
type: package
from: <floco>/package/targets/installed/interface.nix

`scripts`

option: floco.packages.<ident>.<version>.installed.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/installed/interface.nix
example

[
  "build:part1"
  "build:part2"
]

`tree`

option: floco.packages.<ident>.<version>.installed.tree
description: node_modules/ tree used for building.
type: null or package
from: <floco>/package/targets/installed/interface.nix

`key`

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: unique package identifier
from: <floco>/package/interface.nix
example: @floco/test/4.2.0

`lint`

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.

`preferMultipleOutputDerivations`

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

`prepared`

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

`source`

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

`test`

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.

`trees`

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 (null or package)
from: <floco>/package/trees/interface.nix

`dev`

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

`prod`

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

`supported`

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

`dev`

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

`key`

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: unique package identifier
from: <floco>/package/trees/interface.nix
example: @floco/test/4.2.0

`pdefs`

option: floco.pdefs
description: Collection of pdef metadata records for all known packages and modules.

These records are used to generate build recipes and build plans.

Members are structured as a hierarchy of attrsets keyed by ident, with children keyed by version.

`records`

option: floco.records
description: Abstract records used to construct instances of common submodule types.

These base interface must be implemented, but the implementations themselves may be swapped or overridden.

type: submodule
from: <floco>/records/pjsCore/module.nix <floco>/records/interface.nix

`pdef`

option: floco.records.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>/records/pdef/deferred.nix

`binInfo`

option: floco.records.pdef.binInfo
description: Indicates files or directories which should be prepared for use as executable scripts.
type: submodule
from: <floco>/records/pdef/binInfo/interface.nix

`binDir`

option: floco.records.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>/records/pdef/binInfo/interface.nix

`binPairs`

option: floco.records.pdef.binInfo.binPairs
description: Pairs of { <NAME> = <REL-PATH>; ... } indicating executables that will installed, and their associated source code to be symlinked.

These can be used “as is” to set <PKG-ENT>.binInfo.binPairs.

type: attribute set of string
from: <floco>/records/pdef/binInfo/interface.nix
example

{
  semver = "bin/semver.js";
}

`depInfo`

option: floco.records.pdef.depInfo
description: Information regarding dependency modules/packages.

This record is analogous to the various package.json:.[dev|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: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/implementation.generic.nix:depInfoGenericMemberInit”><libfloco>/types/depInfo/implementation.generic.nix:depInfoGenericMemberInit

`bundled`

option: floco.records.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: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred

`descriptor`

option: floco.records.pdef.depInfo.<name>.descriptor
description: A package “descriptor” or “specifier” being either a semantic version number, or a URI.
type: version or URI
from: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred
example: ^4.2.0

`dev`

option: floco.records.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: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred

`optional`

option: floco.records.pdef.depInfo.<name>.optional
description: Whether the dependency may be omitted from the node_modules/ tree during post-distribution phases.

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: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred

`pin`

option: floco.records.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.

In the case of conflicts, the “latest” version will be used. The sorting algorithm prefers pre-releases over a release of the same version, following the behavior of nix-env -u. Read that again.

TODO: Write a sort that makes more sense. Honestly though this is a rare edge case in properly maintained software.

type: pinned version
from: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred

`runtime`

option: floco.records.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: <a href=”https://github.com/aakropotkin/floco/blob/main/modules/types/depInfo/base.nix:depInfoBaseEntryDeferred”><libfloco>/types/depInfo/base.nix:depInfoBaseEntryDeferred

`fetchInfo`

option: floco.records.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>/records/pdef/interface.nix

`fsInfo`

option: floco.records.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>/records/pdef/fsInfo/interface.nix

`dir`

option: floco.records.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>/records/pdef/fsInfo/interface.nix

`gypfile`

option: floco.records.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>/records/pdef/fsInfo/interface.nix

`shrinkwrap`

option: floco.records.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>/records/pdef/fsInfo/interface.nix

`ident`

option: floco.records.pdef.ident
description: Package identifier/name as found in package.json:.name.
type: package identifier/name
from: <floco>/records/pdef/interface.nix
example: @floco/foo

`key`

option: floco.records.pdef.key
description: Unique key used to refer to this package in tree submodules and other floco configs, metadata, and structures.
type: unique package identifier
from: <floco>/records/pdef/interface.nix
example: @floco/test/4.2.0

`lifecycle`

option: floco.records.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.

`build`

option: floco.records.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>/records/pdef/lifecycle/interface.nix

`install`

option: floco.records.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>/records/pdef/lifecycle/interface.nix

`ltype`

option: floco.records.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.

`peerInfo`

option: floco.records.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>/records/pdef/peerInfo/interface.nix

`descriptor`

option: floco.records.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>/records/pdef/peerInfo/single.interface.nix

`optional`

option: floco.records.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>/records/pdef/peerInfo/single.interface.nix

`sourceInfo`

option: floco.records.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>/records/pdef/interface.nix

`outPath`

option: floco.records.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>/records/pdef/interface.nix

`sysInfo`

option: floco.records.pdef.sysInfo
description: Indicates platform, arch, and Node.js version support.
type: submodule
from: <floco>/records/pdef/sysInfo/interface.nix

`cpu`

option: floco.records.pdef.sysInfo.cpu
description: List of supported CPU architectures.

The string "*" indicates that all CPUs are supported.

type: unique list of (one of “*”, “x86_64”, “i686”, “aarch”, “aarch64”, “powerpc64le”, “mipsel”, “riscv64”, “unknown”)
from: <floco>/records/pdef/sysInfo/interface.nix

`engines`

option: floco.records.pdef.sysInfo.engines
description: Indicates supported tooling versions.
type: attribute set of string
from: <floco>/records/pdef/sysInfo/interface.nix

`node`

option: floco.records.pdef.sysInfo.engines.node
description: Supported Node.js versions.
type: string
from: <floco>/records/pdef/sysInfo/interface.nix
example: >=14

`os`

option: floco.records.pdef.sysInfo.os
description: List of supported operating systems.

The string "*" indicates that all operating systems are supported.

type: unique list of (one of “*”, “darwin”, “freebsd”, “netbsd”, “linux”, “openbsd”, “sunprocess”, “win32”, “unknown”)
from: <floco>/records/pdef/sysInfo/interface.nix

`treeInfo`

option: floco.records.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>/records/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;
    # ...
  };
  # ...
}

`dev`

option: floco.records.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>/records/pdef/treeInfo/single.interface.nix

`key`

option: floco.records.pdef.treeInfo.<name>.key
description: Unique key used to refer to this package in tree submodules and other floco configs, metadata, and structures.
type: unique package identifier
from: <floco>/records/pdef/treeInfo/single.interface.nix
example: @floco/test/4.2.0

`link`

option: floco.records.pdef.treeInfo.<name>.link
description: Whether the dependency can by symlinked into node_modules/.

When symlinks are enabled the global target for a package must be defined, and its <global>/lib/node_modules directory contents will be symlinked into the consumer’s node_modules/ directory.

When symlinks are enabled it is an error to declare any subpaths in treeInfo under a “linked” dependency.

type: boolean
from: <floco>/records/pdef/treeInfo/single.interface.nix

`optional`

option: floco.records.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>/records/pdef/treeInfo/single.interface.nix

`version`

option: floco.records.pdef.version
description: Package version as found in package.json:.version.
type: semantic version number
from: <floco>/records/pdef/interface.nix
example: 4.2.0

`pjsCore`

option: floco.records.pjsCore
type: submodule
from: <floco>/records/pjsCore/module.nix

`deferred`

option: floco.records.pjsCore.deferred
description: The deferred form of a pjsCore record.
type: module
from: <floco>/records/pjsCore/module.nix

`mkOpt`

option: floco.records.pjsCore.mkOpt
description: Defines a pjsCore option.
type: raw value
from: <floco>/records/pjsCore/module.nix

`settings`

option: floco.settings
description: Global settings used by various submodules.

These are organized at the top level for the convenience of the user.

type: submodule
from: <floco>/settings/interface.nix

`basedir`

option: floco.settings.basedir
description: Directory used to form relative paths when serializing fetchInfo records to a file.
type: null or path
from: <floco>/settings/interface.nix

`system`

option: floco.settings.system
description: System pair used as build and host platform.
type: one of “x86_64-linux”, “x86_64-darwin”, “aarch64-linux”, “aarch64-darwin”, “i686-linux”, “unknown”
from: <floco>/settings/interface.nix
example: x86_64-linux

`topo`

option: floco.topo
description: Functions and metadata associated with topologically sorting build plans.
type: submodule
from: <floco>/topo/interface.nix

`toposortNoPins`

option: floco.topo.toposortNoPins
description: A function which topologically sorts a list of pdef records.

Package versions are ignored entirely - dependency relationships are established strictly by matching name values to dependencies, optionalDependencies, and devDependencies keys.

type: function that evaluates to a(n) (submodule)
from: <floco>/topo/interface.nix

`toposortPins`

option: floco.topo.toposortPins
description: A function which topologically sorts a list of pdef records.

Package versions are matched using <pdef>.depInfo.*.pin fields. It is an error to call this function with missing pin values on ANY pdef records.

type: function that evaluates to a(n) (submodule)
from: <floco>/topo/interface.nix

`toposortedAll`

option: floco.topo.toposortedAll
description: A toposorted form of all floco.pdefs records.

This routine is expected to run slowly and should be referenced sparingly. Ideally you should only refer to this when optimizing build plans to be rewritten to disk.

This routine uses toposortNoPins if all pdef records have a single version, or toposortPins if multiple versions exist. It is an error to reference this value if these restrictions are not met.

type: submodule
from: <floco>/topo/interface.nix