pyrox.dev
1# Factor {#sec-language-factor}
2
3## Development Environment {#ssec-factor-dev-env}
4
5All Nix expressions for the Factor compiler and development environment can be found in `pkgs/top-level/factor-packages.nix`.
6
7The 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.
8It 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.
9
10For 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.
11The package is defined in `pkgs/development/compilers/factor-lang/wrapper.nix` and provides several attributes for adding those:
12
13- `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.
14- `binPackages` does the same as `extraLibs` and additionally adds the packages to Factor's PATH environment variable.
15- `extraVocabs` adds Factor vocabularies to the tree that are not part of the standard library.
16 The packages must adhere to the default vocabulary root structure to be found.
17- `guiSupport` draws in all necessary graphical libraries to enable the Factor GUI.
18 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).
19 This argument is `true` by default.
20- `enableDefaults` can be deactivated to only wrap libraries that are named in `extraLibs` or `binPackages`.
21 This reduces the runtime dependencies especially when shipping Factor applications.
22
23The package also passes through several attributes listing the wrapped libraries and binaries, namely, `extraLibs` and `binPackages` as well as `defaultLibs` and `defaultBins`.
24Additionally, all `runtimeLibs` is the concatenation of all the above for the purpose of providing all necessary dynamic libraries as "`propagatedBuildInputs`".
25
26`factorPackages` provides pre-configured Factor packages:
27- `factorPackages.factor-lang` is the default package with GUI support and several default library bindings (e.g. openssl, openal etc.).
28- `factorPackages.factor-no-gui` turns off GUI support while maintaining default library bindings.
29- `factorPackages.factor-minimal` comes with practically no additional library bindings and binaries and no GUI support.
30- `factorPackages.factor-minimal-gui` comes with no additional library bindings but includes GUI support.
31
32### Scaffolding and the `work` vocabulary root {#ssec-factor-scaffolding}
33
34Factor uses the concept of "scaffolding" to spin off a new vocabulary in a personal workspace rooted at the `work` vocabulary root.
35This concept does not scale very well, because it makes many assumptions which all turn out to be wrong at some point.
36In the current implementation, the `work` vocabulary root points to `/var/lib/factor` on the target machine.
37This can be suitable for a single-user system.
38Create the location and make it writable to your user.
39Then, you can use the `scaffold-work` word as instructed by many tutorials.
40
41If 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.
42Use `scaffold-vocab` to create your vocabularies in one of these additional roots.
43The online Factor documentation is extensive on how to use the scaffolding framework.
44
45## Packaging Factor Vocabularies {#ssec-factor-packaging}
46
47All Factor vocabularies that shall be added to a Factor environment via the `extraVocabs` attribute must adhere to the following directory scheme.
48Its top-level directory must be one (or multiple) of `basis`, `core` or `extra`.
49`work` is routed to `/var/lib/factor` and is not shipped nor referenced in the nix store, see the section on [scaffolding](#ssec-factor-scaffolding).
50You should usually use `extra`, but you can use the other roots to overwrite built-in vocabularies.
51Be aware that vocabularies in `core` are part of the Factor image which the development environment is run from.
52This means the code in those vocabularies is not loaded from the sources, such that you need to call `refresh-all` to recompile and load the changed definitions.
53In these instances, it is advised to override the `factor-unwrapped` package directly, which compiles and packages the core Factor libraries into the default Factor
54image.
55
56As per Factor convention, your vocabulary `foo.factor` must be in a directory of the same name in addition to one of the previously mentioned vocabulary roots, e.g. `extra/foo/foo.factor`.
57
58All extra Factor vocabularies are registered in `pkgs/top-level/factor-packages.nix` and their package definitions usually live in `development/compilers/factor-lang/vocabs/`.
59
60Package a vocabulary using the `buildFactorVocab` function.
61Its default `installPhase` takes care of installing it under `out/lib/factor`.
62It also understands the following special attributes:
63- `vocabName` is the path to the vocabulary to be installed.
64 Defaults to `pname`.
65- `vocabRoot` is the vocabulary root to install the vocabulary under.
66 Defaults to `extra`.
67 Unless you know what you are doing, do not change it.
68 Other readily understood vocabulary roots are `core` and `basis`, which allow you to modify the default Factor runtime environment with an external package.
69- `extraLibs`, `extraVocabs`, `extraPaths` have the same meaning as for [applications](#ssec-factor-applications).
70 They have no immediate effect and are just passed through.
71 When building factor-lang packages and Factor applications that use this respective vocabulary, these variables are evaluated and their paths added to the runtime environment.
72
73The function understands several forms of source directory trees:
741. Simple single-vocab projects with their Factor and supplementary files directly in the project root.
75 All `.factor` and `.txt` files are copied to `out/lib/factor/<vocabRoot>/<vocabName>`.
762. More complex projects with several vocabularies next to each other, e.g. `./<vocabName>` and `./<otherVocab>`.
77 All directories except `bin`, `doc` and `lib` are copied to `out/lib/factor/<vocabRoot>`.
783. Even more complex projects that touch multiple vocabulary roots.
79 Vocabularies must reside under `lib/factor/<root>/<vocab>` with the name-giving vocabulary being in `lib/factor/<vocabRoot>/<vocabName>`.
80 All directories in `lib/factor` are copied to `out/`.
81
82For instance, packaging the Bresenham algorithm for line interpolation looks like this, see `pkgs/development/compilers/factor-lang/vocabs/bresenham` for the complete file:
83```nix
84{ factorPackages, fetchFromGitHub }:
85
86factorPackages.buildFactorVocab {
87 pname = "bresenham";
88 version = "dev";
89
90 src = fetchFromGitHub {
91 owner = "Capital-EX";
92 repo = "bresenham";
93 rev = "58d76b31a17f547e19597a09d02d46a742bf6808";
94 hash = "sha256-cfQOlB877sofxo29ahlRHVpN3wYTUc/rFr9CJ89dsME=";
95 };
96}
97```
98
99The vocabulary goes to `lib/factor/extra`, extra files, like licenses etc. would go to `share/` as usual and could be added to the output via a `postInstall` phase.
100In case the vocabulary binds to a shared library or calls a binary that needs to be present in the runtime environment of its users, add `extraPaths` and `extraLibs` attributes, respectively.
101They are then picked up by the `buildFactorApplication` function and added as runtime dependencies.
102
103## Building Applications {#ssec-factor-applications}
104
105Factor applications are built using Factor's `deploy` facility with the help of the `buildFactorApplication` function.
106
107### `buildFactorApplication` function {#ssec-factor-buildFactorApplication-func}
108
109`factorPackages.buildFactorApplication` *`buildDesc`*
110
111When packaging a Factor application with [`buildFactorApplication`](#ssec-factor-buildFactorApplication-func), its [`override`](#sec-pkg-override) interface should contain the `factorPackages` argument.
112For example:
113```nix
114{
115 lib,
116 fetchurl,
117 factorPackages,
118}:
119
120factorPackages.buildFactorApplication (finalAttrs: {
121 pname = "foo";
122 version = "1.0";
123
124 src = fetchurl {
125 url = "https://some-forge.org/foo-${finalAttrs.version}.tar.gz";
126 };
127})
128```
129
130The `buildFactorApplication` function expects the following source structure for a package `foo-1.0` and produces a `/bin/foo` application:
131```
132foo-1.0/
133 foo/
134 foo.factor
135 deploy.factor
136 <more files and directories>...
137```
138
139It provides the additional attributes `vocabName` and `binName` to cope with naming deviations.
140The `deploy.factor` file controls how the application is deployed and is documented in the Factor online documentation on the `deploy` facility.
141
142Use the `preInstall` or `postInstall` hooks to copy additional files and directories to `out/`.
143The function itself only builds the application in `/lib/factor/` and a wrapper in `/bin/`.
144
145A more complex example shows how to specify runtime dependencies and additional Factor vocabularies at the example of the `painter` Factor application:
146```nix
147{
148 lib,
149 fetchFromGitHub,
150 factorPackages,
151 curl,
152}:
153
154factorPackages.buildFactorApplication (finalAttrs: {
155 pname = "painter";
156 version = "1";
157
158 factor-lang = factorPackages.factor-minimal-gui;
159
160 src = fetchFromGitHub {
161 name = finalAttrs.vocabName;
162 owner = "Capital-EX";
163 repo = "painter";
164 rev = "365797be8c4f82440bec0ad0a50f5a858a06c1b6";
165 hash = "sha256-VdvnvKNGcFAtjWVDoxyYgRSyyyy0BEZ2MZGQ71O8nUI=";
166 };
167
168 sourceRoot = ".";
169
170 enableUI = true;
171 extraVocabs = [ factorPackages.bresenham ];
172
173 extraPaths = with finalAttrs.factor-lang; binPackages ++ defaultBins ++ [ curl ];
174
175})
176```
177
178The use of the `src.name` and `sourceRoot` attributes conveniently establish the necessary `painter` vocabulary directory that is needed for the deployment to work.
179
180It requires the packager to specify the full set of binaries to be made available at runtime.
181This enables the standard pattern for application packages to specify all runtime dependencies explicitly without the Factor runtime interfering.
182
183`buildFactorApplication` is a wrapper around `stdenv.mkDerivation` and takes all of its attributes.
184Additional attributes that are understood by `buildFactorApplication`:
185
186*`buildDesc`* (Function or attribute set)
187
188: A build description similar to `stdenv.mkDerivation` with the following attributes:
189
190 `vocabName` (String; _optional_)
191
192 : is the path to the vocabulary to be deployed relative to the source root.
193 So, directory `foo/` from the example above could be `extra/deep/down/foo`.
194 This allows you to maintain Factor's vocabulary hierarchy and distribute the same source tree as a stand-alone application and as a library in the Factor development environment via the `extraVocabs` attribute.
195
196 `binName` (String; _optional_)
197
198 : is the name of the resulting binary in `/bin/`.
199 It defaults to the last directory component in `vocabName`.
200 It is also added as the `meta.mainProgram` attribute to facilitate `nix run`.
201
202 `enableUI` (Boolean; _optional_)
203
204 : is `false` by default.
205 Set this to `true` when you ship a graphical application.
206
207 `extraLibs` (List; _optional_)
208
209 : adds additional libraries as runtime dependencies.
210 Defaults to `[]` and is concatenated with `runtimeLibs` from the used factor-lang package.
211 Use `factor-minimal` to minimize the closure of runtime libraries.
212
213 `extraPaths` (List; _optional_)
214
215 : adds additional binaries to the runtime PATH environment variable (without adding their libraries, as well).
216 Defaults to `[]` and is concatenated with `defaultBins` and `binPackages` from the used factor-lang package.
217 Use `factor-minimal` to minimize the closure of runtime libraries.
218
219 `deployScriptText` (String; _optional_)
220
221 : is the actual deploy Factor file that is executed to deploy the application.
222 You can change it if you need to perform additional computation during deployment.
223
224 `factor-lang` (Package; _optional_)
225
226 : overrides the Factor package to use to deploy this application, which also affects the default library bindings and programs in the runtime PATH.
227 It defaults to `factor-lang` when `enableUI` is turned on and `factor-no-gui` when it is turned off.
228 Applications that use only Factor libraries without external bindings or programs may set this to `factor-minimal` or `factor-minimal-gui`.