source: README@ ed335a31

ablfs-more trunk
Last change on this file since ed335a31 was 0fa52f2, checked in by Pierre Labastie <pierre.labastie@…>, 3 years ago

Remove legacy: Remove almost all occurrences of CLFS/clfs

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