source: README.BLFS@ 5e9076f

ablfs
Last change on this file since 5e9076f was d7818f5, checked in by Pierre Labastie <pierre@…>, 13 years ago

Updates to README and README.BLFS. First "alpha release"

  • Property mode set to 100644
File size: 12.4 KB
Line 
1$Id$
2
31. INTRODUCTION::
4
5 If you want to add blfs-tool support into an xLFS base system build,
6 read the "BLFS_TOOL SUPPORT" section found in the README and be sure
7 to follow the after-booting installation intructions.
8
9 To automate package builds from the BLFS book instructions is a huge
10 task. Some of the issues are: the BLFS book isn't linear; some package
11 pages use a custom layout; there are circular dependencies; several
12 packages can be installed on a non-default prefix; build commands can
13 change based on what dependencies will be used, etc.
14
15 That being said, the goal of the blfs-tool is to help you solve package
16 dependencies, create build scripts and a Makefile. Few of the auto-generated
17 build scripts and Makefile will work "as is", thus, as a general rule,
18 you will need to review and edit the scripts while reading the book.
19
20
212. PREREQUISITES::
22
23 To use this tool you MUST:
24
25 - have experience building BLFS packages
26 - know how to edit and write shell scripts
27 - know how a Makefile works
28 - be able to trace build failures and to find what is causing it
29 (user error, package bug, BLFS command bug, or jhalfs code bug)
30
31 If you do not have the above skills, please don't use this tool.
32
33
343. USAGE::
35
36 Due the complexity of the BLFS book, the scripts and Makefile generation
37 is done in several steps:
38
39 3.1 INSTALLED PACKAGES TRACKING SYSTEM::
40
41 This tool includes a very simple tracking system to log which packages
42 have been installed using the tool. It is used to skip installed packages
43 from target selection menu and to test if an installed package has been
44 updated in the BLFS book. Do not rely on this feature as a package
45 management tool.
46
47 The tracking system itself is an XML file: instpkg.xml. It is
48 initialized when <make> is first run in blfs_root. It resides in a
49 directory, which is created when needed during the process of building
50 custom tools or blfs dependencies, right after xLFS. You can specify
51 that directory location in the blfs-tools submenu of jhalfs. You may
52 need to update permissions and/or ownership of this directory before
53 using the blfs tool (see README in jhalfs).
54
55 The default location of the tracking directory is /var/lib/jhalfs/BLFS.
56 NB : after the initial build, that directory is only used to contain
57 instpkg.xml
58
59 3.2 BLFS_TOOL INSTALLATION::
60
61 The tools are installed just after the building of xLFS, if the
62 appropriate options have been selected in the building menu, as per
63 jhalfs README. If you forgot to select the options and xLFS has been
64 built, it is possible to go back to selecting the appropriate
65 BLFS tools options in the jhalfs menu, then tick `Run makefile'
66 and not `Rebuild files'. You obtain a /blfs_root directory in the
67 root directory of the new xLFS system, which contains the followings:
68
69 blfs-xml/* SVN tree of the selected BLFS book version
70 lib/constants.inc functions libraries
71 /func_dependencies for building the dependency tree
72 menu/* lxdialog and menuconfig source code
73 xsl/gen_pkg_list.xsl XSL stylesheet to generate the package database
74 /gen_config.xsl XSL stylesheet to generate the Config.in file
75 for use in the menuconfig system
76 /dependencies.xsl XSL stylesheet to generate the dependency list
77 of a package
78 /make_book.xsl XSL stylesheet to generate the linear book.xml
79 /scripts.xsl XSL stylesheet to generate the scriptlets from
80 book.xml
81 /bump.xsl XSL stylesheet to generate to update the tracking
82 file
83 README.BLFS this file
84 TODO developers notes (well, not updated often)
85 gen_pkg_book.sh resolves dependencies and generates linear BLFS
86 books and build scripts
87 gen-makefile.sh generates the target Makefile
88 progress_bar.sh the target Makefile progress bar
89 gen-special.sh Helper script for generating the package database
90 Makefile Used by make to update the package database from
91 the SVN tree, then launch the menuconfig interface,
92 and run gen_pkg_book.sh based on configuration
93 settings
94 packdesc.dtd a simple DTD describing the format of the package
95 database and the tracking file.
96 envars.conf envars needed when running the target build scripts
97
98 Several files are generated during the process:
99
100 packages.xml auto-generated packages database
101 Config.in input file for the menu driven choices
102 configuration file generated by the menuconfig process
103 dependencies/* files recording the dependency tree
104 book.xml the linearized book
105 book-html/* the linearized book rendered in html
106 scripts/* the scriptlets
107
108 From now on, all the work must be done from inside the installation
109 root directory.
110
111 You may move that directory to the $HOME of a non root user, or build
112 as root from that directory.
113
114 3.3 UPDATING BOOK SOURCES::
115
116 If you are using the development book version and you want to update
117 installed packages to the latest version found in that book, you need to
118 update the XML sources and packages database. This is not necessary if
119 you just built xLFS, and you can skip to step 3.4.
120
121 To do that run "make update". It may happen that the subversion
122 version of your building host is older than the version you just
123 built. This may generate weird errors like "'.' omitted". The easiest
124 thing to do in that case, is to completely remove the blfs-xml directory
125 and run "make update".
126
127 On the next configuration run, packages already installed but listed
128 with a new version in the book will be available for target selection
129 and used to solve dependencies.
130
131 3.4 CONFIGURING AND PARSING THE BOOK::
132
133 The next step is to create a book and build scripts in dependency
134 build order for one or several packages.
135
136 Run <make> to launch the configuration interface. The main menu contains
137 two blocks: individual package selection, and build options.
138
139 In the build options section, the dependencies level and default packages
140 used to solve alternatives are set (currently, only for the MTA). You can
141 also select whether the build will be made as a normal user or as root.
142 Those settings are saved to be reused in future configuration runs.
143
144 Note that you may select as many targets as you want, not just one
145 as in the previous version of this tool. But we suggest to not select
146 too many at a time to be able to sort issues!
147
148 When you are done with the menu, a few checks occur, and the book is
149 generated. When circular dependencies are found, a 3 line message is
150 printed:
151 A is a dependency of B
152 C is a dependency of A
153 A is a dependency of C
154 and a question:
155 Do you want to build A first?
156 This means that the system has found the dependency chain: B->A->C->A.
157 You have therefore to choose whether A is built before C, or
158 C before A: the system cannot make that choice (well, maybe in a few
159 year, with an AI system able to understand the book). If you answer no,
160 C is built first. If you answer yes, C is put in place of A as a dependency
161 of B, then the tree dependency restarts from there, that is with the
162 layout B->C->... You may then hit the case B->C->A->C, for which you
163 should answer no, unless you want to enter an infinite (human driven) loop.
164
165 You end up with a book.xml file which contains the linearized book,
166 and a rendered HTML, in the directory book-html, which you can browse with
167 "lynx book-html/index.html" (or with any other browser).
168
169 Furthermore, there is a directory "scripts", which contains the generated
170 scriptlets.
171
172 There is also another directory, "dependencies" that contains files
173 generated while resolving dependencies.
174
175 3.5 EDITING BUILD SCRIPTS::
176
177 Now it is time to review the generated book and scripts, making any
178 changes to the scripts necessary to fix generation bugs or to suit your
179 needs.
180
181 Scripts for additional packages (i.e., for non-BLFS packages) can be
182 easily inserted. For example, if you want to install the external dependency
183 "bar" before "foo" package and the "foo" script is named "064-z-foo", you
184 just need to create a "064-y-bar" build script.
185
186 Remember, the package tracking system isn't a package management tool
187 and knows nothing about packages not in the BLFS book.
188
189 Also, review and edit envars.conf. This file is used to set global envars
190 needed by the build scripts.
191
192 3.6 CREATING THE MAKEFILE::
193
194 When the build scripts are ready to be run, the Makefile can be
195 created. Create an empty directory (for example "mkdir work") and cd
196 to that directory. Then run ../gen-makefile.sh
197
198 Review the Makefile, and, if all looks sane, start the build by running
199 "make".
200
2014. GENERATED BUILD SCRIPTS ISSUES::
202
203 In this section, known issues with the generated build scripts are
204 discussed. They are due to build procedures and/or BLFS layout
205 particularities that we can't handle. In several cases, editing the
206 build scripts is mandatory.
207 You may also need to insert some build scripts created by you to resolve
208 unhandled dependencies and/or to remove some script installing the affected
209 package by hand.
210
211 4.1 BLFS BOOTSCRIPTS::
212
213 Normally, bootscript installation should work. On the other hand, the
214 book does not give instruction for running them, so you might have to
215 manually insert /etc/init.d/rd.d/<initscript> at some place during the build.
216
217 4.2 PACKAGE CONFIGURATION::
218
219 For those packages that have a "Configuration" section, you should
220 edit the build script to fit the needs of your system. Sometimes, the
221 bash startup files are modified (see for example the instructions for
222 llvm). You might have to insert something like "source /etc/bash_profile"
223 at some point during the build.
224
225 4.3 GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
226
227 On the pages for those packages, the BLFS book actually has instructions
228 to download and install two or more packages. You must edit the scripts to
229 fix this.
230
231 We will try to fix some of them, but this may not be possible.
232
233 4.4 XORG7
234
235 The generated scripts for Xorg7 packages have $SRC_ARCHIVE
236 support for individual packages, but not for patches nor *.wget and *.md5
237 files.
238
239 If you have previously downloaded the patches, you must edit
240 the scripts to use your local packages.
241
242 The *.wget and *.md5 files should be downladed always from inside
243 the scripts to be sure that the most current individual packages are
244 used. Thus don't reuse previously existing ones.
245
246 4.5 PATCHES
247
248 By default, all required patches will be downloaded from the NET.
249
250 If you have previously downloaded the patches, you must edit the
251 scripts to use your local patches.
252
253 Also, be sure that all scripts have the commands to download/apply the
254 required patches. Due to book layout issues, some patches may be missing.
255
256 4.6 ROOT COMMANDS
257
258 If building as a normal user (the default setting), be sure that all
259 commands that require root privileges are run using sudo. Also make sure
260 necessary root privilege commands are visible in your PATH. Or use
261 the `Defaults secure_path=' in /etc/sudoers. Also, the scripts use a
262 fragile construct:
263 sudo bash -c '<commands to be executed as root>'
264 which fail if the commands to be executed contain themselves a ' or access
265 a bash variable $XXX. So carefully review them.
266
267 Due to book layout issues, some sudo commands may be missing.
268
269 4.7 OTHERS
270
271 There may be other issues that we are not aware of. If you find
272 any, please report it to <alfs-discuss@linuxfromscratch.org>.
273
274 Presently, there is an error in the book in file
275 x/installing/x7proto.xml. You should change the role='required' to
276 role='optional' in the optional dependencies, if you plan to build
277 X.
Note: See TracBrowser for help on using the repository browser.