1 Introduction
2 ============
3
4 This is a collection of L4Re packages for providing and using filesystems and
5 related components.
6
7 This directory (departure) should be installed within the pkg directory in the
8 L4Re distribution.
9
10 More information can be found in the docs directory in this distribution.
11
12 * For reading in a text editor, see docs/wiki/Departure
13 * For reading in a Web browser, see docs/html/index.html
14
15 A Note about the Documentation
16 ------------------------------
17
18 The original content in docs/wiki aims to be readable as plain text under most
19 circumstances, but the intention is that this content be translated to HTML
20 since it employs a formatting language based on the MoinMoin wiki format
21 syntax.
22
23 The following command can be used to generate the HTML form of the
24 documentation from the main directory of this distribution:
25
26 ./docs/tools/make_docs.sh
27
28 Specify the --web option for Web server deployment:
29
30 ./docs/tools/make_docs.sh --web
31
32 To generate individual documents, specify their names after any options.
33
34 Prerequisites
35 =============
36
37 This software requires some other software to be useful:
38
39 * The Fiasco.OC microkernel and L4Re distribution
40 * The idl4re distribution
41
42 Obtaining and Building idl4re
43 =============================
44
45 The idl4re distribution provides a tool called idl that generates source files
46 from interface descriptions. It can be obtained as follows:
47
48 hg clone https://hg.boddie.org.uk/L4Re/idl4re
49
50 The software can be built as follows:
51
52 cd idl4re
53 make
54
55 When building the Departure software within the L4Re build system, the idl4re
56 directory will need to be present in the appropriate location, this being
57 inside the l4 directory. The easiest way of satisfying this requirement is to
58 copy or move the idl4re directory into the l4 directory, making sure that the
59 software is built before trying to build L4Re itself.
60
61 Obtaining and Building Fiasco.OC and L4Re
62 =========================================
63
64 Although the build processes for Fiasco.OC and L4Re are generally documented,
65 the concise instructions for building the software have not been preserved in
66 the L4Re distribution, requiring the perusal of online resources. For example:
67
68 https://github.com/kernkonzept/manifest/wiki/BUILDING
69
70 Some reminders are provided below to save the reader the bother of looking up
71 or searching for this information, particularly if it does not continue to
72 reside in the above location.
73
74 Obtaining and Building the ham Tool
75 -----------------------------------
76
77 First of all, the ham tool has to be obtained. This can be done as follows:
78
79 git clone https://github.com/kernkonzept/ham.git
80
81 It can be built as follows:
82
83 cd ham
84 make
85
86 Returning to the parent directory, the Fiasco.OC and L4Re distributions can be
87 obtained as follows:
88
89 ham/ham init -u https://github.com/kernkonzept/manifest.git
90 ham/ham sync
91
92 (Referencing ham within its repository avoids any need to put the program on
93 the PATH, which is largely unnecessary since we will only be using it in this
94 particular location and for the specific purpose of downloading the remaining
95 software of interest.)
96
97 Building Fiasco.OC
98 ------------------
99
100 Here is a quick summary of the build process for Fiasco.OC starting at the
101 parent directory of the Fiasco.OC and L4Re distributions:
102
103 cd fiasco
104 make BUILDDIR=mybuild
105 cd mybuild
106 make config
107 make
108
109 The final make command can employ flags such as "-j8" or even "-j" without any
110 parameter to parallelise the build.
111
112 At this point, this directory (departure) can be copied into the L4Re
113 distribution within the pkg directory. Also, the idl4re distribution should be
114 made available within the l4 directory itself.
115
116 Building L4Re
117 -------------
118
119 To build this distribution successfully along with the rest of the L4Re
120 sources, the idl4re distribution must reside within the l4 directory and the
121 idl tool built, as described above, and this distribution must be placed at
122 the pkg/departure location within the l4 directory.
123
124 To summarise:
125
126 l4/
127 idl4re/
128 idl - the built idl tool
129 pkg/
130 departure/
131 README.txt - this file
132
133 Here is a quick summary of the build process for L4Re, also starting at the
134 parent directory of the Fiasco.OC and L4Re distributions:
135
136 cd l4
137 make B=mybuild
138 make O=mybuild config
139 make O=mybuild
140
141 Again, the final make command can employ parallelisation flags. For example:
142
143 make -j8 O=mybuild
144
145 Along with the usual L4Re software, this will also build the software provided
146 by this distribution if the above instructions have been followed.
147
148 Defining the L4Re Configuration
149 ===============================
150
151 An example configuration file is provided as conf/Makeconf.boot within this
152 distribution. Where no such existing file has been deployed, this example file
153 can be copied into a suitable location from within the l4 directory as
154 follows:
155
156 cp pkg/departure/conf/Makeconf.boot conf/Makeconf.boot
157
158 Otherwise, with an existing conf/Makeconf.boot file, to make the test programs
159 available to L4Re, add the following line to such a file:
160
161 MODULE_SEARCH_PATH += $(L4DIR_ABS)/pkg/departure/conf
162
163 It may also be necessary to add the following line as well:
164
165 BOOTSTRAP_SEARCH_PATH += $(L4DIR_ABS)/pkg/departure/conf
166
167 This removes any need to copy program configuration files and associated
168 resources to the L4Re distribution itself.
169
170 Defining the Module Lists
171 =========================
172
173 The program module lists in the conf subdirectory can either be appended to
174 the L4Re conf/modules.list file, or specific .list files can be copied to the
175 conf/modules.list location (potentially after taking a backup copy of the
176 original file). For example, from within the l4 directory:
177
178 cp conf/modules.list conf/modules.list.orig
179 cat pkg/departure/conf/*.list > conf/modules.list
180
181 Running Programs from this Distribution
182 =======================================
183
184 With configuration measures in place, a program can be run in QEMU as follows:
185
186 make O=mybuild qemu E=dstest_test_client
187
188 The particular program used above is a short concurrency test.
189
190 Copyright and Licence Information
191 =================================
192
193 See the following Web pages for more information about this work:
194
195 https://projects.boddie.org.uk/Departure
196
197 The author can be contacted at the following e-mail address:
198
199 paul@boddie.org.uk
200
201 Copyright and licence information can be found in the docs directory - see
202 docs/COPYING.txt and docs/LICENCE.txt for more information.
