source: README.BLFS@ 18c1c95

ablfs
Last change on this file since 18c1c95 was f3fb6ce, checked in by Pierre Labastie <pierre@…>, 13 years ago

Add a script to install the blfs tools to an already running system

  • Property mode set to 100644
File size: 13.3 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. Not all 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 to the complexity of the BLFS book, the scripts and Makefile
37 generation 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, unless custom tools have been built. In the latter case,
58 it also contains empty files whose name are $PKG-$VERSION for each
59 versionned package built. The information about those packages is
60 included into instpkg.xml the next time the tool is run.
61
62 3.2 BLFS_TOOL INSTALLATION::
63
64 3.2.1 Normal install
65 The tools are installed just after the building of xLFS, if the
66 appropriate options have been selected in the building menu, as per
67 jhalfs README. If you forgot to select the options and xLFS has been
68 built, it is possible to go back to selecting the appropriate
69 BLFS tools options in the jhalfs menu, then tick `Run makefile'
70 and not `Rebuild files'. You obtain a /blfs_root directory in the
71 root directory of the new xLFS system, which contains the followings:
72
73 blfs-xml/* SVN tree of the selected BLFS book version
74 lib/constants.inc functions libraries
75 /func_dependencies for building the dependency tree
76 menu/* lxdialog and menuconfig source code
77 xsl/gen_pkg_list.xsl XSL stylesheet to generate the package database
78 /gen_config.xsl XSL stylesheet to generate the Config.in file
79 for use in the menuconfig system
80 /dependencies.xsl XSL stylesheet to generate the dependency list
81 of a package
82 /make_book.xsl XSL stylesheet to generate the linear book.xml
83 /scripts.xsl XSL stylesheet to generate the scriptlets from
84 book.xml
85 /bump.xsl XSL stylesheet to generate to update the tracking
86 file
87 README.BLFS this file
88 TODO developers notes (well, not updated often)
89 gen_pkg_book.sh resolves dependencies and generates linear BLFS
90 books and build scripts
91 gen-makefile.sh generates the target Makefile
92 progress_bar.sh the target Makefile progress bar
93 gen-special.sh Helper script for generating the package database
94 Makefile Used by make to update the package database from
95 the SVN tree, then launch the menuconfig interface,
96 and run gen_pkg_book.sh based on configuration
97 settings
98 packdesc.dtd a simple DTD describing the format of the package
99 database and the tracking file.
100 envars.conf envars needed when running the target build scripts
101
102 3.2.2 Install to an already running LFS/BLFS system
103 If you forgot to install the tools when building xLFS, or want to try
104 the tools, you can just run the install-blfs-tools.sh script. It will
105 create the above hierarchy in your home directory and intialize the
106 tracking file. You have first to make sure that the tracking dir exists
107 and is writable by the user. You may also populate it with (empty) files
108 whose names are of the form package-version, for installed packages, so
109 that they are included into the tracking file.
110 3.3.3 Working files
111 Several files are generated during the process:
112
113 packages.xml auto-generated packages database
114 Config.in input file for the menu driven choices
115 configuration file generated by the menuconfig process
116 dependencies/* files recording the dependency tree
117 book.xml the linearized book
118 book-html/* the linearized book rendered in html
119 scripts/* the scriptlets
120
121 From now on, all the work must be done from inside the installation
122 root directory.
123
124 You may move that directory to the $HOME of a non root user, or build
125 as root from that directory.
126
127 3.3 UPDATING BOOK SOURCES::
128
129 If you are using the development book version and you want to update
130 installed packages to the latest version found in that book, you need to
131 update the XML sources and packages database. This is not necessary if
132 you just built xLFS, and you can skip to step 3.4.
133
134 To do that, run "make update". It may happen that the subversion
135 version of your building host is older than the version you just
136 built. This may generate weird errors like "'.' omitted". The easiest
137 thing to do in that case, is to completely remove the blfs-xml directory
138 and run "make update". With recent versions of subversion, you can also
139 run "svn upgrade" from inside the blfs-xml directory.
140
141 On the next configuration run, packages already installed but listed
142 with a new version in the book will be available for target selection
143 and used to solve dependencies.
144
145 3.4 CONFIGURING AND PARSING THE BOOK::
146
147 The next step is to create a book and build scripts in dependency
148 build order for one or several packages.
149
150 Run <make> to launch the configuration interface. The main menu contains
151 two blocks: individual package selection, and build options.
152
153 In the build options section, the dependencies level and default packages
154 used to solve alternatives are set (currently, only for the MTA). You can
155 also select whether the build will be made as a normal user or as root.
156 Those settings are saved to be reused in future configuration runs.
157
158 Note that you may select as many targets as you want, not just one
159 as in the previous version of this tool. But we suggest to not select
160 too many at a time to be able to sort issues!
161
162 When you are done with the menu, a few checks occur, and the book is
163 generated. When circular dependencies are found, a 3 line message is
164 printed:
165 A is a dependency of B
166 C is a dependency of A
167 A is a dependency of C
168 and a question:
169 Do you want to build A first?
170 This means that the system has found the dependency chain: B->A->C->A.
171 You have therefore to choose whether A is built before C, or
172 C before A: the system cannot make that choice (well, maybe in a few
173 year, with an AI system able to understand the book). If you answer no,
174 C is built first. If you answer yes, C is put in place of A as a dependency
175 of B, then the tree dependency restarts from there, that is with the
176 layout B->C->... You may then hit the case B->C->A->C, for which you
177 should answer no, unless you want to enter an infinite (human driven)
178 loop;-)
179
180 You end up with a book.xml file which contains the linearized book,
181 and a rendered HTML, in the directory book-html, which you can browse with
182 "lynx book-html/index.html" (or with any other browser).
183
184 Furthermore, there is a directory "scripts", which contains the generated
185 scriptlets.
186
187 There is also another directory, "dependencies" that contains files
188 generated while resolving dependencies.
189
190 3.5 EDITING BUILD SCRIPTS::
191
192 Now it is time to review the generated book and scripts, making any
193 changes to the scripts necessary to fix generation bugs or to suit your
194 needs.
195
196 Scripts for additional packages (i.e., for non-BLFS packages) can be
197 easily inserted. For example, if you want to install the external dependency
198 "bar" before "foo" package and the "foo" script is named "064-z-foo", you
199 just need to create a "064-y-bar" build script.
200
201 Remember, the package tracking system isn't a package management tool
202 and knows nothing about packages not in the BLFS book.
203
204 Also, review and edit envars.conf. This file is used to set global envars
205 needed by the build scripts.
206
207 3.6 CREATING THE MAKEFILE::
208
209 When the build scripts are ready to be run, the Makefile can be
210 created. Create an empty directory (for example "mkdir work") and cd
211 to that directory. Then run ../gen-makefile.sh
212
213 Review the Makefile, and, if all looks sane, start the build by running
214 "make".
215
2164. GENERATED BUILD SCRIPTS ISSUES::
217
218 In this section, known issues with the generated build scripts are
219 discussed. They are due to build procedures and/or BLFS layout
220 particularities that we can't handle. In several cases, editing the
221 build scripts is mandatory.
222 You may also need to insert some build scripts created by you to resolve
223 unhandled dependencies and/or to remove some script installing the affected
224 package by hand.
225
226 4.1 BLFS BOOTSCRIPTS::
227
228 Normally, bootscript installation should work. On the other hand, the
229 book does not give instruction for running them, so you might have to
230 manually insert /etc/init.d/rc.d/<initscript> at some place during the build.
231
232 4.2 PACKAGE CONFIGURATION::
233
234 For those packages that have a "Configuration" section, you should
235 edit the build script to fit the needs of your system. Sometimes, the
236 bash startup files are modified (see for example the instructions for
237 llvm). The shipped 'envars.conf' contains a line 'source /etc/profile',
238 which ensures that the proper environment variables are used.
239
240 4.3 GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
241
242 On the pages for those packages, the BLFS book actually has instructions
243 to download and install two or more packages. You must edit the scripts to
244 fix this.
245
246 We will try to fix some of them, but this may not be possible.
247
248 4.4 XORG7
249
250 The generated scripts for Xorg7 packages have $SRC_ARCHIVE
251 support for individual packages, but not for patches nor *.wget and *.md5
252 files.
253
254 If you have previously downloaded the patches, you must edit
255 the scripts to use your local packages.
256
257 The *.wget and *.md5 files should be downladed always from inside
258 the scripts to be sure that the most current individual packages are
259 used. Thus don't reuse previously existing ones.
260
261 In the script for xorg7-font, be sure to move the fonts directories
262 symlinks creation to after the "for ... done" loop.
263
264
265 4.5 PATCHES
266
267 Please, make sure that all scripts have the commands to download/apply
268 the required patches. Due to book layout issues, some patches may be
269 missing.
270
271 4.6 ROOT COMMANDS
272
273 If building as a normal user (the default setting), be sure that all
274 commands that require root privileges are run using sudo. Also make sure
275 necessary root privilege commands are visible in your PATH. Or use
276 the `Defaults secure_path=' in /etc/sudoers. Also, the scripts use a
277 fragile construct:
278 sudo bash -c '<commands to be executed as root>'
279 which fail if the commands to be executed contain themselves a ' or access
280 a bash variable $XXX. So carefully review them. When you want to use
281 environment variables, it is sometimes better to replace simple quotes
282 with double quotes, but beware the construct is even more fragile.
283 Carefully check it...
284
285 Due to book layout issues, some sudo commands may be missing.
286
287 4.7 OTHERS
288
289 There may be other issues that we are not aware of. If you find
290 any, please report it to <alfs-discuss@linuxfromscratch.org>.
291
Note: See TracBrowser for help on using the repository browser.