# Factor {#sec-language-factor}

## Development Environment {#ssec-factor-dev-env}

All Nix expressions for the Factor compiler and development environment can be found in `pkgs/top-level/factor-packages.nix`.

The default package `factor-lang` provides support for the built-in graphical user interface and a selected set of C library bindings, e.g., for sound and TLS connections.
It also comes with the Fuel library for Emacs that provides an integrated development environment for developing Factor programs including access to the Factor runtime and online documentation.

For using less frequently used libraries that need additional bindings, you can override the `factor-lang` package and add more library bindings and/or binaries to its PATH.
The package is defined in `pkgs/development/compilers/factor-lang/wrapper.nix` and provides several attributes for adding those:

- `extraLibs` adds the packages' `/lib` paths to the wrapper and adds all shared libraries to an ld.so cache such that they can be found dynamically by the Factor runtime.
- `binPackages` does the same as `extraLibs` and additionally adds the packages to Factor's PATH environment variable.
- `extraVocabs` adds Factor vocabularies to the tree that are not part of the standard library.
  The packages must adhere to the default vocabulary root structure to be found.
- `guiSupport` draws in all necessary graphical libraries to enable the Factor GUI.
  This should be set to `true` when considering building and running graphical applications with this Factor runtime (even if the Factor GUI is not used for programming).
  This argument is `true` by default.
- `enableDefaults` can be deactivated to only wrap libraries that are named in `extraLibs` or `binPackages`.
  This reduces the runtime dependencies especially when shipping Factor applications.

The package also passes through several attributes listing the wrapped libraries and binaries, namely, `extraLibs` and `binPackages` as well as `defaultLibs` and `defaultBins`.
Additionally, all `runtimeLibs` is the concatenation of all the above for the purpose of providing all necessary dynamic libraries as "`propagatedBuildInputs`".

`factorPackages` provides pre-configured Factor packages:
- `factorPackages.factor-lang` is the default package with GUI support and several default library bindings (e.g. openssl, openal etc.).
- `factorPackages.factor-no-gui` turns off GUI support while maintaining default library bindings.
- `factorPackages.factor-minimal` comes with practically no additional library bindings and binaries and no GUI support.
- `factorPackages.factor-minimal-gui` comes with no additional library bindings but includes GUI support.

### Scaffolding and the `work` vocabulary root {#ssec-factor-scaffolding}

Factor uses the concept of "scaffolding" to spin off a new vocabulary in a personal workspace rooted at the `work` vocabulary root.
This concept does not scale very well, because it makes many assumptions which all turn out to be wrong at some point.
In the current implementation, the `work` vocabulary root points to `/var/lib/factor` on the target machine.
This can be suitable for a single-user system.
Create the location and make it writable to your user.
Then, you can use the `scaffold-work` word as instructed by many tutorials.

If you don't like this approach, you can work around it by creating a `~/.factor-roots` file in your home directory which contains the locations you desire to represent additional Factor vocabulary roots, one directory per line.
Use `scaffold-vocab` to create your vocabularies in one of these additional roots.
The online Factor documentation is extensive on how to use the scaffolding framework.

## Packaging Factor Vocabularies {#ssec-factor-packaging}

All Factor vocabularies that shall be added to a Factor environment via the `extraVocabs` attribute must adhere to the following directory scheme.
Its top-level directory must be one (or multiple) of `basis`, `core` or `extra`.