source: README@ 1814367

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

Small adjustements to READMEs and BLFS/TODO

  • Property mode set to 100644
File size: 12.2 KB
Line 
1$Id$
2
31. INTRODUCTION::
4
5 This collection of scripts, known as jhalfs, strives to create
6 accurate makefiles from the Linux From Scratch book series XML files.
7 This software is an evolution of the original "jhalfs-0.2" code developed
8 by Jeremy Huntwork.
9
10 The usage of this script assumes you have read and are familiar with
11 the book(s) and, therefore, the configuration variables found in menuconfig
12 interface will have meaning to you.
13
14 The list of supported books can be found at
15 http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks
16
17 NOTES::
18 *. The resulting Makefile takes considerable time to run to completion.
19 Lay in a supply of caffeine beverages.
20
21 *. It is recommended that you temporarily unpack your linux kernel,
22 run <make menuconfig>, configure the kernel as per the book and save
23 the resulting .config file.
24
25 *. Read carefully this file and the other README.* files before using
26 this tool.
27
282. PREREQUISITES::
29
30 To use this tool you MUST:
31
32 - have experience building {c,h,b}LFS packages
33 - know how to edit and write shell scripts
34 - know how a Makefile works
35 - be able to trace build failures and to find what is causing them
36 (user error, package bug, {c,h,b}LFS command bug, or jhalfs code bug)
37
38 If you do not have the above skills, please don't use this tool.
39
40
413. INSTALLATION::
42
43 No installation is required. You should just run <make> in this directory.
44
454. CONFIGURATION::
46
47 Configuration is done through a menu based interface. See the section
48 RUNNING, for details.
49
505. RUNNING::
51
52 The command <make> will launch a menu based configuration program. You will
53 recognize the layout from building the kernel or uClibc/BusyBox. The
54 underlying menu code was borrowed from BusyBox and slightly modified for
55 our use.
56
57 Help on parameter function is available from the on-line help. Please
58 make use of that feature: it may contain additional information not
59 duplicated in this file.
60
61 You should first choose which book and flavour you want to build. Note
62 that when you choose the BLFS book, the tool will just install the BLFS
63 tool to your system. You'll have to run that installed tool to build
64 packages in BLFS. See README.BLFS to know how. If you choose any other
65 book, you'll have to configure the settings and the build parameters
66 from the menu. Note that you may choose to install the blfs tools onto
67 the newly built system (see below). It is not the same thing as choosing
68 the BLFS book in the menu, which will install the blfs tools on the
69 currently running system.
70
71
72 Once you have set the parameters and saved the configuration, the script
73 is launched. Its aim is to extract instructions from the selected book
74 to generate scripts, and to generate a Makefile, which allows running
75 the scripts in the right order. The script verifies first that the host
76 can run it and build the xLFS system, then validates the configuration
77 and lists the parameters. At this point, you may choose to quit or to
78 continue with the listed parameters. The script will then proceed to
79 generate the Makefile and the build scripts, optionally download
80 packages, and eventually verify the host prerequisite. If you have
81 selected "Run the makefile", the command make is launched in the
82 adequate directory, and the build begins. If not, you'll have to run
83 "make" manually, for example: "make -C /mnt/build_dir/jhalfs", if you
84 have used the default parameters (see the layout under $BUILDDIR in the
85 Q&A below).
86
87 IMPORTANT::
88 You must be logged as a normal user with sudo privileges to run
89 the Makefile. Furthermore, you are supposed to have enough privilege
90 to become any user. If you are not bothered about security issues,
91 the entry for the user "jhalfs_user" in /etc/sudoers could be
92 jhalfs_user ALL=(ALL) NOPASSWD:ALL
93
94 NOTE::
95 If you run the jhalfs script directly the only function you can select
96 is to display the version number running <./jhalfs -v>
97
986. BLFS_TOOL SUPPORT::
99
100 For books that support it (only LFS for jhalfs version 2.4),
101 there is an option to install an automated framework for building BLFS
102 packages. It is called blfs-tool. When you tick `BOOK Settings/Add
103 blfs-tool support' in jhalfs configuration menu, the tools are
104 installed in $BLFS_ROOT (default /blfs_root) on the xLFS system,
105 and a few dependencies (which you may select) are built at the
106 end of the jhalfs run, before the custom tools. The instructions for
107 building the dependencies are taken from the BLFS book.
108
109 (TODO: blfs-tools have not been tested with current (version 3.0) of CLFS,
110 and certainly need some adaptation to run)
111 WARNING:: If you add blfs-tool support on a CLFS Sysroot build
112 you MUST edit the scripts to fix the installation paths.
113
114 After booting the new xLFS system some steps are needed to finish
115 the installation of the automated tools:
116
117 - A user account must be created. You must be logged on that user
118 account to use blfs-tool. This is not strictly necessary,
119 since the packages can be built as root, too, but it is
120 never a good idea to build packages as root.
121
122 - Move /blfs-root to that user's home and change ownership of the
123 directory and files to the user.
124
125 - Give the user read and write privileges over the $TRACKING_DIR
126 directory and the files that it contains.
127
128 - Configure sudo, adding the needed privileges for the user. For
129 newer sudo version, do not forget to add a line Defaults secure_path=
130 containing /sbin and /usr/sbin (in /etc/sudoers), otherwise some
131 executables are not found.
132
133 - Although it is not strictly necessary, it is recommended to install
134 the bash shell startup files (as per `3.After LFS Configuration
135 Issues' of the BLFS book), as some instructions in BLFS rely on
136 their being present.
137
138 We assume that blfs-tool will be used on a running fresh xLFS system.
139 To use it to build BLFS packages from the chroot jail is also possible,
140 but not supported.
141
142 To know how to use blfs-tool, see README.BLFS.
143
1447. LAYOUT::
145
146 /BLFS (see README.BLFS)
147
148 /CLFS/master.sh
149 /clfs.xsl
150
151 /CLFS2/master.sh
152 /clfs2.xsl
153
154 /CLFS3/master.sh
155 /clfs3.xsl
156
157 /HLFS/master.sh
158 /hlfs.xsl
159
160 /LFS/master.sh
161 /lfs.xsl
162
163 /common/common_functions
164 /makefile_functions
165 /packages.xsl
166 /urls.xsl
167 /create-sbu_du-report.sh
168 /progress_bar.sh
169 /blfs-tool-deps/9xx-*
170 /libs/func_*
171
172 /custom/template
173 /config/
174 /examples/*
175 /examples_CLFS-E/*
176
177 /extras/do_copy_files
178 /do_ica_prep
179 /do_ica_work
180 /farce
181 /filelist
182
183 /optimize/opt_config
184 /opt_override
185 /optimize_functions
186 /opt_config.d/noOpt
187 /noSymbols
188 /O3pipe
189 /O3pipe_march
190 /defOpt_fPIC
191
192 /menu/*
193
194 README
195 README.BLFS
196 README.CLFS
197 README.HLFS
198 README.CUSTOM
199 TODO
200 LICENSE
201
202 Config.in
203 Makefile
204 jhalfs
205 blfs-tool
206
2078. FAQ::
208 Q. "This 'help' file is very sparse"
209 A. Yes, it is. This tool, jhalfs, is for those who understand the LFS books
210 and wish to automate the build. 99% of any problems that arise can be
211 solved by reading the book(s).
212
213 Q. "It doesn't work!"
214 A. Yes it does, try >> make
215 Remember you must have 'sudo' privileges.
216
217 Q. "It still doesn't work"
218 A. jhalfs was designed to work against the development versions of the LFS
219 series of books. Consequently changes in a book(s) sometimes breaks older
220 versions of jhalfs. Before you start pulling out your hair download the
221 latest version of jhalfs to see if that solves your problem.
222
223 Q. "How do I specify the build location?"
224 A. The original LFS document worked against the well known location
225 /mnt/lfs. This script automates the build of all of the LFS series of
226 books and uses a generic location $BUILDDIR with a default value of
227 /mnt/build_dir. You may change this value to suit your needs.
228
229 The layout below $BUILDDIR is as follows.
230 $BUILDDIR/
231 jhalfs (Makefile, cmd scripts, logs, etc..)
232 sources (where packages reside)
233 tools (temporary bootstrap system)
234 cross-tools (temporary CLFS only)
235 ...
236 FHS dir structure
237 ...
238 blfs_root (files to use blfs-tool if selected to install it)
239
240 Q. "What is the function of the SRC_ARCHIVE variable?"
241 A. When jhalfs runs and packages download was selected, it creates a local
242 copy of the necessary packages in BUILDDIR/sources by downloading the
243 files. If the variable SRC_ARCHIVE is defined the software will first
244 look in this location for the file and, if found, will copy it to
245 BUILDDIR/sources.
246 If the files are not found in SRC_ARCHIVE _and_ you have write priv to
247 the directory any downloaded files will be mirrored there.
248
249 Q. "How do I set the SRC_ARCHIVE location?"
250 A. The best way to set the value of SRC_ARCHIVE is
251
252 export SRC_ARCHIVE=/wherever/you/store/downloaded/packages
253
254 or you can set the full path in the proper menu entry.
255
256 Q. "Why have 2 copies of the files?"
257 A. The package files must be visible during the chroot phase and this is a
258 simple and reliable method of doing so. This method also handles the
259 CLFS boot build method where the final build may be done on a separate
260 machine.
261
262 Q. "What is the function of "User account" and "Group account" menu
263 settings?"
264 A. If you are running jhalfs from a low or non-privileged account you may
265 not have the priv to create/delete the user needed to build temporary
266 tools.
267 These settings allow you to use your own user and group name to do those
268 build steps.
269
270 These variables are adjustable also when invoking make:
271
272 $BUILDDIR make LUSER=myaccount LGROUP=mygroup
273
274 The only changes to your account will be the creation of a NEW .bashrc
275 after saving your original to .bashrc.XXX
276
277 Q. "When I try to build CLFS the Makefile fails at mid-point"
278 A. There could be numerous reasons for the failure but the most likely
279 reason is you are doing a cross-build using the 'chroot' method and the
280 target is not compatible with the host. If you choose to build using
281 the chroot method a test is performed at the end of the temptools
282 phase. If the test succeeds the build continues inside a chroot jail.
283 However if the test fails, it means the host and target are not
284 compatible an you should use the 'boot' method to create your target
285 code.
286 As an extreme example: You can build a sparc target on a x86 platform but
287 only the temptools phase. You must select the 'boot' method and not the
288 'chroot.' You must transfer the toolchain to a sparc platform, reboot the
289 sparc box and continue the build.
290 Of all the LFS series of books Cross-LFS requires the greatest
291 understanding of host/target hardware combination. Please read the book
292 carefully and don't skip the easy parts (there are none...)
293
294 Q. "How could I stop the build at a predefined chosen point?"
295 A. Launch the Makefile manually passing the last numbered target to be build
296 as the break point. For example:
297
298 make BREAKPOINT=84-bash
299
300 The build can be stopped also at the end of a top-level build phase by
301 calling directly the appropriate mk_* target. For example:
302
303 make mk_LUSER
304
305 See the Makefile to know the proper target names for that book build.
306
307Authors:
308 George Boudreau
309 Manuel Canales Esparcia
310 Pierre Labastie
Note: See TracBrowser for help on using the repository browser.