source: project/wiki/eggref/5/beaker @ 39528

Last change on this file since 39528 was 39528, checked in by evhan, 5 months ago

wiki/beaker: Update Nix helper docs

File size: 10.8 KB
Line 
1== Beaker
2
3Lab supplies for CHICKEN Scheme.
4
5[[toc:]]
6
7== Description
8
9Beaker is a collection of development tools.
10
11It is currently fairly limited, including only a few programs and a handful
12of libraries to make common development tasks easier. If you have an idea
13for something that would be useful to include, don't hesitate to contact
14the [[#author|author]].
15
16The project's source is available [[https://git.sr.ht/~evhan/beaker|here]].
17
18== Dependencies
19
20* [[/eggref/5/module-declarations|module-declarations]]
21* [[/eggref/5/begin-syntax|begin-syntax]]
22* [[/eggref/5/debugger-protocol|debugger-protocol]]
23* [[/eggref/5/schematic|schematic]]
24* [[/eggref/5/srfi-1|srfi-1]]
25* [[/eggref/5/srfi-13|srfi-13]]
26* [[/eggref/5/srfi-14|srfi-14]]
27* [[/eggref/5/srfi-69|srfi-69]]
28* [[/eggref/5/vector-lib|vector-lib]]
29* [[/eggref/5/with-current-directory|with-current-directory]]
30
31== Programs
32
33=== chicken-clean
34
35 Usage: chicken-clean [-interactive | -quiet | -verbose]
36
37The {{chicken-clean}} program deletes egg build artifacts.
38
39A simple set of file patterns is used to determine what should be
40deleted. This includes compiled programs, binary objects ({{o}}, {{obj}},
41{{so}}, {{dll}}), and files generated by the CHICKEN toolchain ({{build.sh}},
42{{install.sh}}, {{import.scm}}, {{inline}}, {{profile}}, {{types}}).
43
44When run with the {{-interactive}} flag, a confirmation prompt will be
45displayed before any files are deleted.
46
47=== chicken-lint
48
49 Usage: chicken-lint [csc-options ...] filename ...
50
51The {{chicken-lint}} program checks a source file with a set of simple
52lint rules.
53
54Potential problems are written as S-expressions to standard error.
55
56Note that this program invokes {{csc}}, so any compile-time code in the
57program will be executed.
58
59=== chicken-lock
60
61 Usage: chicken-lock [egg ...]
62
63The {{chicken-lock}} program generates a snapshot of all dependency versions
64for the given eggs, or for any egg files in the current directory.
65
66The output is an override file that can then be used to install those same
67versions later on via the "-override" or "-from-list" flags to {{chicken-install}}.
68For example, you can record the current version of the r7rs egg and all of
69its dependencies, and then restore them later, like this:
70
71 $ chicken-lock r7rs > r7rs.lock
72 ... time passes...
73 $ chicken-install -from-list r7rs.lock
74
75If no egg names are given on the command line, this program will look for
76egg files in the current directory. This can be used to record the current
77version of all dependencies for an egg in local development:
78
79 $ cat example.egg
80 ((synopsis "A nice example library")
81  (build-dependencies matchable)
82  (dependencies r7rs)
83  (components (extension example)))
84 $ chicken-lock > example.egg.lock
85 ... time passes ...
86 $ chicken-install -override example.egg.lock
87
88Any extra arguments are passed through to {{chicken-install}} when fetching
89eggs. So, you can use "-override" to fix some subset of an egg's dependency
90versions when generating the snapshot, as well as other options like
91"-verbose" to print more information about what's happening.
92
93== Extensions
94
95=== Repository Management
96
97The {{(beaker repository)}} library provides a handful of procedures
98to help manage egg repositories.
99
100<procedure>(chicken-install)</procedure>
101
102Returns the full pathname of the {{chicken-install}} command.
103
104<procedure>(chicken-status)</procedure>
105
106Returns the full pathname of the {{chicken-status}} command.
107
108<procedure>(egg-files #!optional (path repository-path))</procedure>
109
110Returns a list of all egg-info files in the repository path.
111
112The {{path}} argument can be used to specify an alternative repository
113path, which should be a thunk returning a list of pathname strings.
114
115<procedure>(repair-repository #!optional (path repository-path))</procedure>
116
117Installs any missing dependencies for the eggs in the repository path.
118
119The {{path}} argument can be used to specify an alternative repository
120path, which should be a thunk returning a list of pathname strings.
121
122If there are any missing dependencies, they are installed into the
123first repository in the path and a list of newly-installed eggs is
124returned.
125
126If there are no missing dependencies, nothing is done and an empty
127list is returned.
128
129<procedure>(create-repository destination #!optional source)</procedure>
130
131Initialises a new egg repository at the pathname {{destination}}.
132
133If the directory {{destination}} doesn't exist, it is created. The core
134CHICKEN libraries are then installed into the repository and a new
135modules database is generated
136
137If a {{source}} repository is given, its contents are also copied into
138the new repository. This can be used to copy an existing repository
139to another location.
140
141=== Systems
142
143The {{(beaker system)}} library provides an API for dynamically
144building, loading, and reloading extension libraries. It's intended
145to help enable rapid development in a manner similar to [[https://common-lisp.net/project/asdf/asdf/index.html|asdf]] from
146Common Lisp or the [[https://wiki.call-cc.org/eggref/4/system|system]] egg from CHICKEN 4.
147
148Rather than introduce a new way to define a system's components and
149dependencies, this library reuses the [[http://wiki.call-cc.org/man/5/Egg%20specification%20format|egg]] specification format.
150In fact, you can generally think of a "system" and an "egg" as one
151and the same.
152
153An example {{csi}} session that loads, edits, and reloads an example
154system might look like the following:
155
156 #;> (import (beaker system))
157 #;> (load-system "example.egg")
158 building example
159 ... output ...
160 ; loading /tmp/temp70d6.29489.example.import.so ...
161 ; loading /tmp/temp4871.29489.example.so ...
162 #;> (load-system "example.egg")
163 building example
164 #;> ,e example.scm
165 #;> (load-system "example.egg")
166 building example
167 ... output ...
168 ; loading /tmp/temp44a2.29609.example.so ...
169
170Modules are imported automatically and import libraries are reloaded
171whenever a module's exports list changes. Note that removing a value
172from a module's export list does not remove it from the session when
173the extension is reloaded.
174
175<procedure>(compile-system egg-file)</procedure>
176
177Compiles all out-of-date components for the given egg.
178
179This is equivalent to running {{chicken-install -no-install}}.
180
181<procedure>(clean-system egg-file)</procedure>
182
183Deletes all compiled programs and extension libraries for the given egg.
184
185Auxiliary files such as import libraries are preserved.
186
187<procedure>(load-system egg-file #!key (skip (quote ())))</procedure>
188
189Builds and loads the given egg.
190
191When called for the first time, all out-of-date components are
192recompiled, the egg's extension libraries are loaded into the calling
193program and its modules are immediately imported.
194
195Subsequent calls cause the components to be recompiled and reloaded
196as necessary.
197
198== Nix Helpers
199
200This project also includes some helper functions for the [[https://nixos.org/|Nix]]
201package manager that make it easy to build CHICKEN programs.
202
203=== Usage
204
205The helpers can be imported directly from the Git repository archive:
206
207 let
208   beaker = import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/master.tar.gz) {};
209 in
210   doStuff { with beaker; ... }
211
212This library only includes two attributes, so it's also relatively harmless to
213pull into scope, for example:
214
215 with import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/3679375a.tar.gz) {};
216 
217 eggProgram {
218   name = "example";
219   src = ./.;
220   eggCache = eggCache {
221     eggs = ./example.egg.lock;
222     hash = "sha256:00x5k7rhs1fy7fj5kma1yp2ikzbq98bfm33si5y8z8m25chb45sg";
223   };
224 }
225
226=== Fetching Egg Dependencies
227
228<procedure>eggCache attrSet</procedure>
229
230A fixed-output derivation that fetches a set of eggs for installation.
231
232The list of eggs to cache should be specified via {{eggs}}, which expects a path
233to a file in "override" specifying a list of egg names and versions. This file
234can be generated via {{chicken-status -list}} (for installed eggs) or
235{{chicken-lock}} (for a specific egg's dependencies).
236
237 eggCache {
238   name = "example-egg-cache";
239   hash = "sha256:03pz5927dkazrf8hf53w03r80ca98fwp09gmd8iiywxc5vl8ll2m";
240   eggs = ./eggs.lock;
241 }
242
243Alternatively, you can specify the list of eggs directly:
244
245 eggCache {
246   name = "example-egg-cache";
247   hash = "sha256:01fq1398aj4r54yw6ym8i56i236yb3pvmn6a54iahz09cp615g2x";
248   eggs = [
249     { name = "srfi-18"; version = "0.1"; }
250     { name = "srfi-69"; version = "0.4"; }
251   ];
252 }
253
254==== Combining Multiple Egg Caches
255
256To merge multiple egg caches, you can use {{symlinkJoin}}:
257
258 pkgs.symlinkJoin {
259   name = "example-egg-caches";
260   paths = [
261     (eggCache { ... })
262     (eggCache { ... })
263   ];
264 }
265
266The result will be a single egg cache containing all of the specified eggs.
267Note that if any input paths contain different versions of the same egg, the
268first one listed takes precedence.
269
270=== Building Eggs
271
272<procedure>eggProgram attrSet</procedure>
273
274Builds any eggs in the given {{src}} directory, bundling all dependencies and
275placing the resulting binaries into {{<path>/bin}}.
276
277Egg dependencies must be provided via {{eggCache}} so that all inputs are known
278at build time. If any dependencies are missing from the cache, the build will
279fail with the error message {{"extension or version not found: <egg>"}}.
280
281 eggProgram {
282   name = "example-program";
283   src = ./.;
284   eggCache = eggCache { ... };
285 }
286
287Apart from {{eggCache}}, this derivation accepts all the same attributes as
288{{stdenv.mkDerivation}}.
289
290== Links
291
292* Sources: [[https://git.sr.ht/~evhan/beaker]]
293* Issues: [[https://todo.sr.ht/~evhan/beaker]]
294* Documentation: [[https://api.call-cc.org/5/doc/beaker]]
295
296== Author
297
298[[/users/evan-hanson|Evan Hanson]]
299
300== License
301
302 Copyright (c) 2015-2021, Evan Hanson <evhan@foldling.org>
303 All rights reserved.
304 
305 Redistribution and use in source and binary forms, with or without
306 modification, are permitted provided that the following conditions
307 are met:
308 
309   * Redistributions of source code must retain the above copyright
310     notice, this list of conditions and the following disclaimer.
311   * Redistributions in binary form must reproduce the above copyright
312     notice, this list of conditions and the following disclaimer in the
313     documentation and/or other materials provided with the distribution.
314   * The name of the author may not be used to endorse or promote products
315     derived from this software without specific prior written permission.
316 
317 THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
318 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
319 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
320 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
321 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
322 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
323 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
324 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
325 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
326 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
327
328[[tags: egg]]
Note: See TracBrowser for help on using the repository browser.