source: README@ 91b7b5f

ablfs-more legacy trunk
Last change on this file since 91b7b5f was cc8dba9, checked in by Pierre Labastie <pierre@…>, 8 years ago

Refactor two README files

  • Property mode set to 100644
File size: 14.9 KB
Line 
1$Id$
2
31. INTRODUCTION::
4
5 The scripts in this directory implement an automation of the building
6 of a GNU/LInux system, as described in the Linux From Scratch book series.
7 The name of the project is jhalfs: in that name, "alfs" stands for
8 "automated linux from scratch", and the initials "jh" have been kept since
9 the original "jhalfs-0.2" code developed by Jeremy Huntwork.
10
11 The list of supported books can be found at
12 http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks.
13
14 The documentation is split among various README.* files. Here is a list
15 of what is in which:
16 - README (this file): instructions to use the LFS book. This should be
17 enough if you just want to build a base system as per the LFS book. It is
18 also a required reading for all the other projects.
19 - README.CLFS: supplementary instructions to use the CLFS book series.
20 - README.BLFS: instructions to install an automated build infrastructure
21 for the BLFS book. There are two ways to do so: (i) install the
22 tools at the end of an LFS build (CLFS is not supported in that case), or
23 (ii) install the tools on an already running system. Both methods are
24 described in that file.
25 - README.CUSTOM: instructions to run custom commands either during the xLFS
26 build, at the end of a xLFS build. Note that you will not find
27 instructions on how to write those commands, but some examples are
28 available.
29 - README.PACKAGE_MANAGEMENT: instructions to use package management during
30 the build (only for LFS, patches welcome for CLFS...)
31 - README.HLFS: very short file explaining why you cannot use HLFS with the
32 present tool version.
33
34 Other sources of information are the context help in the menu interface,
35 and the xLFS books themselves.
36
372. PREREQUISITES::
38
39 As said elsewhere, it is strongly advised that you first build manually
40 a complete system before attempting to automate the build.
41
42 Of course the "Host System Requirements" should be fulfilled. The needed
43 supplementary packages are detailed at the bottom of the page:
44 http://www.linuxfromscratch.org/alfs/download.html
45
463. INSTALLATION::
47
48 No installation is required. You may want to move the files in this
49 directory to a convenient location, and then follow the instructions below.
50
514. CONFIGURATION::
52
53 4.1. CONFIGURATION OF THE TOOLS:
54 There is no configuration of the tools themselves. The various
55 parameters for the build are set through a menu driven interface. See
56 the section RUNNING below for details.
57
58 4.2. PRELIMINARY TASKS:
59 This tool has no support at all for creating a partition and a mount
60 point for the built system. You should follow the book up to the section
61 "Mounting the new partition". Note that the default name for the
62 partition mount point is "/mnt/build_dir", instead of /mnt/{c,}lfs.
63 You can change that default to anything you'd like in the menu, so you
64 may name it /mnt/lfs, or whatever you like. One important point is that
65 the user you are logged in as (and not the (c)lfs user) should have write
66 permission to the mounted directory. We'll use the name /mnt/build_dir
67 in the sequel.
68
69 The tool can download the needed packages for you, or you may download
70 them yourself. The tool may optionally use a package archive directory
71 where the downloaded packages are stored. That directory name may be made
72 available to the tool in two ways: (i) export the SRC_ARCHIVE variable,
73 for example SRC_ARCHIVE=/usr/src, (ii) enter the name at the "Package
74 Archive Directory" menu prompt. Note that the user should have write
75 permission to that directory. If a needed package is found in that
76 directory, it is copied to /mnt/build_dir/sources, if not, it is
77 downloaded to that directory and copied to /mnt/build_dir/sources,
78 except if found in /mnt/build_dir/sources, in which case, it is just
79 copied to $SRC_ARCHIVE. If you want the tool to download packages and you
80 do not want to archive them, just unset SRC_ARCHIVE, and keep the
81 default entry for "Package Archive Directory". If you choose to download
82 the packages by yourself, you should download (or copy) them to
83 /mnt/build_dir/sources directly.
84
85 If you want to build the kernel as part of the automated build, select
86 "Build the kernel" in the menu. Then, a configuration file must be
87 provided. In order to do so, it is recommended to download the kernel
88 tarball, unpack it, run <make menuconfig>, configure the kernel as per
89 the book, and save the resulting .config file to a location where it can
90 be retrieved later on (a convenient location and name is
91 $SRC_ARCHIVE/config-<arch>-<kernel version>-<config details>).
92
93 Another file you may provide is the fstab file. To use it, select
94 "Use a custom fstab file" in the menu interface, and enter the name of
95 the file where asked. As for the kernel configuration, this file has to
96 be prepared before running the menu. A convenient location and name is
97 $SRC_ARCHIVE/fstablfs.
98
99 At a more advanced level, you may want to supply custom commands
100 to be run at the end of (C)LFS build. Scripts containing those commands
101 are located in the ./custom/config directory. Examples are given in
102 ./custom/examples. A template is provided as ./custom/template. See
103 README.CUSTOM for more details.
104
1055. RUNNING::
106
107 The command <make> will launch a menu based configuration program. The
108 underlying menu code was borrowed from BusyBox and slightly modified for
109 our use.
110
111 Help on parameter function is available from the on-line help. Please
112 make use of that feature: it may contain additional information not
113 duplicated in this file.
114
115 You should first choose which book and flavour you want to build. Note
116 that when you choose the BLFS book, the tool will just install the BLFS
117 tool to your system. You'll have to run that installed tool to build
118 packages in BLFS. See README.BLFS to know how. If you choose any other
119 book, you'll have to configure the settings and the build parameters
120 from the menu. Note that you may choose to install the blfs tools onto
121 the newly built system. It is not the same thing as choosing
122 the BLFS book in the menu, which will install the blfs tools on the
123 currently running system.
124
125 The "General Settings" menu is where the "Build Directory" name is to be
126 entered. Other entries in that menu select what the tool should do. The
127 "Run the Makefile" entry selects whether the tool will start the build
128 automatically after generating the needed files. The "Rebuild files" selects
129 whether to clean the build directory before doing anything else. To protect
130 against removing important files, this can only be done in an empty directory,
131 or a directory previously populated by the tool.
132
133 The "Build Settings" menu is where various options for the build can be
134 selected. Two options, "Use a custom fstab file" and "Build the kernel",
135 have been described above. "Do not use/display progress_bar", if set, will
136 prevent a progress bar to be displayed during the build. That may be useful
137 on slow machine. The other options should be self explanatory, using either
138 the online help or book reading.
139
140 The "Advanced Features" menu is for various maintenance tasks, like
141 testing the build instructions or reporting build statistics. One useful
142 option is "Optimization and parallelisation". It is not recommended to use
143 it for setting compiler optimization flags, although it is possible, but
144 if you select it, you'll be able to select the number of parallel `make'
145 jobs, which allows much faster builds on modern multicore CPUs.
146
147 Once you have set the parameters and saved the configuration, the script
148 is launched. Its aim is to extract instructions from the selected book
149 to generate scripts, and to generate a Makefile, which allows running
150 the scripts in the right order. The script verifies first that the host
151 can run itself and build the xLFS system, then validates the configuration
152 and lists the parameters. At this point, you may choose to quit or to
153 continue with the listed parameters. The script will then proceed to
154 generate the Makefile and the build scripts, optionally download
155 packages, and eventually verify the host prerequisite. If you have
156 selected "Run the makefile", the command <make> is launched in the
157 adequate directory, and the build begins. If not, you'll have to run
158 "make" manually, for example: "make -C /mnt/build_dir/jhalfs", if you
159 have used the default parameters (see the layout under $BUILDDIR in the
160 Q&A below).
161
162 IMPORTANT::
163 You must be logged as a normal user with sudo privileges to run
164 the Makefile. Furthermore, you are supposed to have enough privilege
165 to become any user. If you are not bothered about security issues,
166 the entry for the user "jhalfs_user" in /etc/sudoers could be
167 jhalfs_user ALL=(ALL) NOPASSWD:ALL
168
169 NOTE::
170 If you run the jhalfs script directly the only function you can select
171 is to display the version number by running <./jhalfs -v>
172
1736. LAYOUT::
174
175 /BLFS (see README.BLFS)
176
177 /CLFS/master.sh
178 /clfs.xsl
179
180 /CLFS2/master.sh
181 /clfs2.xsl
182
183 /CLFS3/master.sh
184 /clfs3.xsl
185
186 /HLFS/master.sh
187 /hlfs.xsl
188
189 /LFS/master.sh
190 /lfs.xsl
191
192 /common/common_functions
193 /makefile_functions
194 /packages.xsl
195 /urls.xsl
196 /create-sbu_du-report.sh
197 /progress_bar.sh
198 /blfs-tool-deps/9xx-*
199 /libs/func_*
200
201 /custom/template
202 /config/
203 /examples/*
204 /examples_CLFS-E/*
205
206 /extras/do_copy_files
207 /do_ica_prep
208 /do_ica_work
209 /farce
210 /filelist
211
212 /optimize/opt_config
213 /opt_override
214 /optimize_functions
215 /opt_config.d/noOpt
216 /noSymbols
217 /O3pipe
218 /O3pipe_march
219 /defOpt_fPIC
220
221 /menu/*
222
223 README
224 README.BLFS
225 README.CLFS
226 README.HLFS
227 README.CUSTOM
228 TODO
229 LICENSE
230
231 Config.in
232 Makefile
233 jhalfs
234 blfs-tool
235
2367. FAQ::
237 Q. "It doesn't work"
238 A. There are several reasons why it may be so. One possibility is the
239 following:jhalfs was designed to work against the development versions
240 of the LFS series of books. Consequently changes in a book(s) sometimes
241 breaks older versions of jhalfs. Before you start pulling out your hair
242 download the latest version of jhalfs to see if that solves your
243 problem. Note that it may be the other way around. If you want to build
244 an old version of the book, you may have to downgrade you jahlfs
245 version.
246
247 Q. "How do I specify the build location?"
248 A. The original LFS document worked against the well known location
249 /mnt/lfs. This script automates the build of all of the LFS series of
250 books and uses a generic location $BUILDDIR with a default value of
251 /mnt/build_dir. You may change this value to suit your needs.
252
253 The layout below $BUILDDIR is as follows.
254 $BUILDDIR/
255 jhalfs (Makefile, cmd scripts, logs, etc..)
256 sources (where packages reside)
257 tools (temporary bootstrap system)
258 cross-tools (temporary CLFS only)
259 ...
260 FHS dir structure
261 ...
262 blfs_root (files to use blfs-tool if selected to install it)
263
264 Q. "What is the function of the SRC_ARCHIVE variable?"
265 A. When jhalfs runs and packages download was selected, it creates a local
266 copy of the necessary packages in BUILDDIR/sources by downloading the
267 files. If the variable SRC_ARCHIVE is defined the software will first
268 look in this location for the file and, if found, will copy it to
269 BUILDDIR/sources.
270 If the files are not found in SRC_ARCHIVE _and_ you have write priv to
271 the directory any downloaded files will be mirrored there.
272
273 Q. "How do I set the SRC_ARCHIVE location?"
274 A. The best way to set the value of SRC_ARCHIVE is
275
276 export SRC_ARCHIVE=/wherever/you/store/downloaded/packages
277
278 or you can set the full path in the proper menu entry.
279
280 Q. "Why have 2 copies of the files?"
281 A. The package files must be visible during the chroot phase and this is a
282 simple and reliable method of doing so. This method also handles the
283 CLFS boot build method where the final build may be done on a separate
284 machine.
285
286 Q. "What is the function of "User account" and "Group account" menu
287 settings?"
288 A. If you are running jhalfs from a low or non-privileged account you may
289 not have the priv to create/delete the user needed to build temporary
290 tools.
291 These settings allow you to use your own user and group name to do those
292 build steps.
293
294 These variables are adjustable also when invoking make:
295
296 $BUILDDIR make LUSER=myaccount LGROUP=mygroup
297
298 The only changes to your account will be the creation of a NEW .bashrc
299 after saving your original to .bashrc.XXX
300
301 Q. "When I try to build CLFS the Makefile fails at mid-point"
302 A. There could be numerous reasons for the failure but the most likely
303 reason is you are doing a cross-build using the 'chroot' method and the
304 target is not compatible with the host. If you choose to build using
305 the chroot method a test is performed at the end of the temptools
306 phase. If the test succeeds the build continues inside a chroot jail.
307 However if the test fails, it means the host and target are not
308 compatible an you should use the 'boot' method to create your target
309 code.
310 As an extreme example: You can build a sparc target on a x86 platform but
311 only the temptools phase. You must select the 'boot' method and not the
312 'chroot.' You must transfer the toolchain to a sparc platform, reboot the
313 sparc box and continue the build.
314 Of all the LFS series of books Cross-LFS requires the greatest
315 understanding of host/target hardware combination. Please read the book
316 carefully and don't skip the easy parts (there are none...)
317
318 Q. "How could I stop the build at a predefined chosen point?"
319 A. Launch the Makefile manually passing the last numbered target to be build
320 as the break point. For example:
321
322 make BREAKPOINT=84-bash
323
324 The build can be stopped also at the end of a top-level build phase by
325 calling directly the appropriate mk_* target. For example:
326
327 make mk_LUSER
328
329 See the Makefile to know the proper target names for that book build.
330
331Authors:
332 George Boudreau
333 Manuel Canales Esparcia
334 Pierre Labastie
Note: See TracBrowser for help on using the repository browser.