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