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 re-compile 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 `base`, 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{
85 factorPackages,
86 fetchFromGitHub,
87}:
88
89factorPackages.buildFactorVocab {
90 pname = "bresenham";
91 version = "dev";
92
93 src = fetchFromGitHub {
94 owner = "Capital-EX";
95 repo = "bresenham";
96 rev = "58d76b31a17f547e19597a09d02d46a742bf6808";
97 hash = "sha256-cfQOlB877sofxo29ahlRHVpN3wYTUc/rFr9CJ89dsME=";
98 };
99}
100```
101
102The 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.
103In 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.
104They are then picked up by the `buildFactorApplication` function and added as runtime dependencies.
105
106## Building Applications {#ssec-factor-applications}
107
108Factor applications are built using Factor's `deploy` facility with the help of the `buildFactorApplication` function.
109
110### `buildFactorApplication` function {#ssec-factor-buildFactorApplication-func}
111
112`factorPackages.buildFactorApplication` *`buildDesc`*
113
114When packaging a Factor application with [`buildFactorApplication`](#ssec-factor-buildFactorApplication-func), its [`override`](#sec-pkg-override) interface should contain the `factorPackages` argument.
115For example:
116```nix
117{
118 lib,
119 fetchurl,
120 factorPackages,
121}:
122
123factorPackages.buildFactorApplication (finalAttrs: {
124 pname = "foo";
125 version = "1.0";
126
127 src = fetchurl {
128 url = "https://some-forge.org/foo-${finalAttrs.version}.tar.gz";
129 };
130})
131```
132
133The `buildFactorApplication` function expects the following source structure for a package `foo-1.0` and produces a `/bin/foo` application:
134```
135foo-1.0/
136 foo/
137 foo.factor
138 deploy.factor
139 <more files and directories>...
140```
141
142It provides the additional attributes `vocabName` and `binName` to cope with naming deviations.
143The `deploy.factor` file controls how the application is deployed and is documented in the Factor online documentation on the `deploy` facility.
144
145Use the `preInstall` or `postInstall` hooks to copy additional files and directories to `out/`.
146The function itself only builds the application in `/lib/factor/` and a wrapper in `/bin/`.
147
148A more complex example shows how to specify runtime dependencies and additional Factor vocabularies at the example of the `painter` Factor application:
149```nix
150{
151 lib,
152 fetchFromGitHub,
153 factorPackages,
154 curl,
155}:
156
157factorPackages.buildFactorApplication (finalAttrs: {
158 pname = "painter";
159 version = "1";
160
161 factor-lang = factorPackages.factor-minimal-gui;
162
163 src = fetchFromGitHub {
164 name = finalAttrs.vocabName;
165 owner = "Capital-EX";
166 repo = "painter";
167 rev = "365797be8c4f82440bec0ad0a50f5a858a06c1b6";
168 hash = "sha256-VdvnvKNGcFAtjWVDoxyYgRSyyyy0BEZ2MZGQ71O8nUI=";
169 };
170
171 sourceRoot = ".";
172
173 enableUI = true;
174 extraVocabs = [ factorPackages.bresenham ];
175
176 extraPaths = with finalAttrs.factor-lang; binPackages ++ defaultBins ++ [ curl ];
177
178})
179```
180
181The use of the `src.name` and`sourceRoot` attributes conveniently establish the necessary `painter` vocabulary directory that is needed for the deployment to work.
182
183It requires the packager to specify the full set of binaries to be made available at runtime.
184This enables the standard pattern for application packages to specify all runtime dependencies explicitly without the Factor runtime interfering.
185
186`buildFactorApplication` is a wrapper around `stdenv.mkDerivation` and takes all of its attributes.
187Additional attributes that are understood by `buildFactorApplication`:
188
189*`buildDesc`* (Function or attribute set)
190
191: A build description similar to `stdenv.mkDerivation` with the following attributes:
192
193 `vocabName` (String; _optional_)
194
195 : is the path to the vocabulary to be deployed relative to the source root.
196 So, directory `foo/` from the example above could be `extra/deep/down/foo`.
197 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.
198
199 `binName` (String; _optional_)
200
201 : is the name of the resulting binary in `/bin/`.
202 It defaults to the last directory component in `vocabName`.
203 It is also added as the `meta.mainProgram` attribute to facilitate `nix run`.
204
205 `enableUI` (Boolean; _optional_)
206
207 : is `false` by default.
208 Set this to `true` when you ship a graphical application.
209
210 `extraLibs` (List; _optional_)
211
212 : adds additional libraries as runtime dependencies.
213 Defaults to `[]` and is concatenated with `runtimeLibs` from the used factor-lang package.
214 Use `factor-minimal` to minimize the closure of runtime libraries.
215
216 `extraPaths` (List; _optional_)
217
218 : adds additional binaries to the runtime PATH environment variable (without adding their libraries, as well).
219 Defaults to `[]` and is concatenated with `defaultBins` and `binPackages` from the used factor-lang package.
220 Use `factor-minimal` to minimize the closure of runtime libraries.
221
222 `deployScriptText` (String; _optional_)
223
224 : is the actual deploy Factor file that is executed to deploy the application.
225 You can change it if you need to perform additional computation during deployment.
226
227 `factor-lang` (Package; _optional_)
228
229 : overrides the Factor package to use to deploy this application, which also affects the default library bindings and programs in the runtime PATH.
230 It defaults to `factor-lang` when `enableUI` is turned on and `factor-no-gui` when it is turned off.
231 Applications that use only Factor libraries without external bindings or programs may set this to `factor-minimal` or `factor-minimal-gui`.