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

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

eggref/beaker: Update docs

File size: 5.5 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 two programs and a small
12handful of libraries to make common development tasks easier. If you
13have an idea for something that would be useful to include, don't
14hesitate to contact the [[#author|author]].
15
16The project's source is available [[https://git.sr.ht/~evhan/beaker|here]].
17
18== Dependencies
19
20* [[/eggref/5/begin-syntax|begin-syntax]]
21* [[/eggref/5/debugger-protocol|debugger-protocol]]
22* [[/eggref/5/module-declarations|module-declarations]]
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== Extensions
60
61=== Repository Management
62
63The {{(beaker repository)}} library provides a handful of procedures
64to help manage egg repositories.
65
66<procedure>(chicken-install)</procedure>
67
68Returns the full pathname of the {{chicken-install}} command.
69
70<procedure>(egg-files #!optional (path repository-path))</procedure>
71
72Returns a list of all egg-info files in the repository path.
73
74The {{path}} argument can be used to specify an alternative repository
75path, which should be a thunk returning a list of pathname strings.
76
77<procedure>(repair-repository #!optional (path repository-path))</procedure>
78
79Installs any missing dependencies for the eggs in the repository path.
80
81The {{path}} argument can be used to specify an alternative repository
82path, which should be a thunk returning a list of pathname strings.
83
84If there are any missing dependencies, they are installed into the
85first repository in the path and a list of newly-installed eggs is
86returned.
87
88If there are no missing dependencies, nothing is done and an empty
89list is returned.
90
91<procedure>(create-repository destination #!optional source)</procedure>
92
93Initialises a new egg repository at the pathname {{destination}}.
94
95If the directory {{destination}} doesn't exist, it is created. The core
96CHICKEN libraries are then installed into the repository and a new
97modules database is generated
98
99If a {{source}} repository is given, its contents are also copied into
100the new repository. This can be used to copy an existing repository
101to another location.
102
103=== Systems
104
105The {{(beaker system)}} library provides an API for dynamically
106building, loading, and reloading extension libraries. It's intended
107to help enable rapid development in a manner similar to [[https://common-lisp.net/project/asdf/asdf/index.html|asdf]] from
108Common Lisp or the [[https://wiki.call-cc.org/eggref/4/system|system]] egg from CHICKEN 4.
109
110Rather than introduce a new way to define a system's components and
111dependencies, this library reuses the [[http://wiki.call-cc.org/man/5/Egg%20specification%20format|egg]] specification format.
112In fact, you can generally think of a "system" and an "egg" as one
113and the same.
114
115An example {{csi}} session that loads, edits, and reloads an example
116system might look like the following:
117
118 #;> (import (beaker system))
119 #;> (load-system "example.egg")
120 building example
121 ... output ...
122 ; loading /tmp/temp70d6.29489.example.import.so ...
123 ; loading /tmp/temp4871.29489.example.so ...
124 #;> (load-system "example.egg")
125 building example
126 #;> ,e example.scm
127 #;> (load-system "example.egg")
128 building example
129 ... output ...
130 ; loading /tmp/temp44a2.29609.example.so ...
131
132Modules are imported automatically and import libraries are reloaded
133whenever a module's exports list changes. Note that removing a value
134from a module's export list does not remove it from the session when
135the extension is reloaded.
136
137<procedure>(compile-system egg-file)</procedure>
138
139Compiles all out-of-date components for the given egg.
140
141This is equivalent to running {{chicken-install -no-install}}.
142
143<procedure>(clean-system egg-file)</procedure>
144
145Deletes all compiled programs and extension libraries for the given egg.
146
147Auxiliary files such as import libraries are preserved.
148
149<procedure>(load-system egg-file #!key (skip (quote ())))</procedure>
150
151Builds and loads the given egg.
152
153When called for the first time, all out-of-date components are
154recompiled, the egg's extension libraries are loaded into the calling
155program and its modules are immediately imported.
156
157Subsequent calls cause the components to be recompiled and reloaded
158as necessary.
159
160== Links
161
162* Sources: [[https://git.sr.ht/~evhan/beaker]]
163* Issues: [[https://todo.sr.ht/~evhan/beaker]]
164* Documentation: [[https://api.call-cc.org/5/doc/beaker]]
165
166== Author
167
168[[/users/evan-hanson|Evan Hanson]]
169
170== License
171
1723-Clause BSD
173
174[[tags: egg]]
Note: See TracBrowser for help on using the repository browser.