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

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

wiki/beaker: Document Nix helpers

File size: 10.1 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 -override r7rs.lock r7rs
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
200=== Usage
201
202This library's Nix helpers can be imported from the Git repository archive:
203
204 let
205   beaker = import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/master.tar.gz) {};
206 in
207   doStuff { ... }
208
209The project's {{default.nix}} only includes two helpers so it's also relatively
210harmless to pull into scope, for example:
211
212 with import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/6bfb584b.tar.gz) {};
213 
214 eggProgram {
215   name = "example";
216   src = ./.;
217   eggCache = eggCache {
218     overrideFile = ./example.egg.lock;
219     hash = "sha256:00x5k7rhs1fy7fj5kma1yp2ikzbq98bfm33si5y8z8m25chb45sg";
220   };
221 }
222
223=== Fetching Egg Dependencies
224
225<procedure>eggCache attrSet</procedure>
226
227A fixed-output derivation that fetches a set of eggs for installation.
228
229The list of eggs to cache should be specified via {{overrideFile}}, which
230expects a path to a file in "override" specifying a list of egg names and
231versions. This file can be generated via {{chicken-status -list}} (for installed
232eggs) or {{chicken-lock}} (for a specific egg's dependencies).
233
234 eggCache {
235   name = "example-egg-cache"
236   overrideFile = ./eggs.lock
237   hash = "sha256:03pz5927dkazrf8hf53w03r80ca98fwp09gmd8iiywxc5vl8ll2m"
238 }
239
240=== Building Eggs
241
242<procedure>eggProgram attrSet</procedure>
243
244Builds any eggs in the given {{src}} directory, bundling all dependencies and
245placing the resulting binaries into {{<path>/bin}}.
246
247Egg dependencies must be provided via {{eggCache}} so that all inputs are known
248at build time. If any dependencies are missing from the cache, the build will
249fail with the error message {{"extension or version not found: <egg>"}}.
250
251 eggProgram {
252   name = "example-program";
253   src = ./.;
254   eggCache = eggCache { ... };
255 }
256
257Apart from {{eggCache}}, this derivation accepts all the same attributes as
258{{stdenv.mkDerivation}}.
259
260== Links
261
262* Sources: [[https://git.sr.ht/~evhan/beaker]]
263* Issues: [[https://todo.sr.ht/~evhan/beaker]]
264* Documentation: [[https://api.call-cc.org/5/doc/beaker]]
265
266== Author
267
268[[/users/evan-hanson|Evan Hanson]]
269
270== License
271
272 Copyright (c) 2015-2021, Evan Hanson <evhan@foldling.org>
273 All rights reserved.
274 
275 Redistribution and use in source and binary forms, with or without
276 modification, are permitted provided that the following conditions
277 are met:
278 
279   * Redistributions of source code must retain the above copyright
280     notice, this list of conditions and the following disclaimer.
281   * Redistributions in binary form must reproduce the above copyright
282     notice, this list of conditions and the following disclaimer in the
283     documentation and/or other materials provided with the distribution.
284   * The name of the author may not be used to endorse or promote products
285     derived from this software without specific prior written permission.
286 
287 THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
288 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
289 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
290 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
291 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
292 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
293 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
294 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
295 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
296 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
297
298[[tags: egg]]
Note: See TracBrowser for help on using the repository browser.