source: README.BLFS@ c67990f

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

Update READMEs

  • Property mode set to 100644
File size: 14.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 instructions.
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 sub-menu 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 update the tracking file
86 README.BLFS this file
87 TODO developers notes (well, not updated often)
88 gen_pkg_book.sh resolves dependencies and generates linear BLFS
89 books and build scripts
90 gen-makefile.sh generates the target Makefile
91 progress_bar.sh the target Makefile progress bar
92 gen-special.sh Helper script for generating the package database
93 Makefile Used by make to update the package database from
94 the SVN tree, then launch the menuconfig interface,
95 and run gen_pkg_book.sh based on configuration
96 settings
97 packdesc.dtd a simple DTD describing the format of the package
98 database and the tracking file.
99 envars.conf envars needed when running the target build scripts
100
101 3.2.2 Install to an already running LFS/BLFS system
102 If you forgot to install the tools when building xLFS, or want to try
103 the tools, you can select the BLFS book from the jhalfs menu. It will
104 run a script, which creates the above hierarchy in your home directory and
105 initialize the tracking file. You have first to make sure that the tracking
106 dir exists and is writable by the user. You may also populate it with
107 (empty) files whose names are of the form package-version, for installed
108 packages, so that they are included into the tracking file.
109
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 dependency
163 chain is generated. Each dependency appears with its priority (required,
164 recommended, optional, or external), and it's level. There is a root level
165 1. The selected packages have level 2. The dependencies of selected packages
166 have level 3, the dependencies of the dependencies have level 4, and so on.
167 When circular dependencies are found, they appear with a priority of
168 "circular". This means that two (or more) dependency chains arrive at the
169 same package. The algorithm chooses the chain with the highest priority and
170 reorders dependencies to remove the other chain(s). This is not always the
171 solution an user would prefer, but we have found no way to do it better.
172
173 You end up with a book.xml file which contains the linearized book,
174 and a rendered HTML, in the directory book-html, which you can browse with
175 "lynx book-html/index.html" (or with any other browser).
176
177 Furthermore, there is a directory "scripts", which contains the generated
178 scriptlets.
179
180 There is also another directory, "dependencies" that contains files
181 generated while resolving dependencies.
182
183 3.5 EDITING BUILD SCRIPTS::
184
185 Now it is time to review the generated book and scripts, making any
186 changes to the scripts necessary to fix generation bugs or to suit your
187 needs.
188
189 Scripts for additional packages (i.e., for non-BLFS packages) can be
190 easily inserted. For example, if you want to install the external dependency
191 "bar" before "foo" package and the "foo" script is named "064-z-foo", you
192 just need to create a "064-y-bar" build script.
193
194 Remember, the package tracking system isn't a package management tool
195 and knows nothing about packages not in the BLFS book.
196
197 Also, review and edit envars.conf. This file is used to set global envars
198 needed by the build scripts.
199
200 3.6 CREATING THE MAKEFILE::
201
202 When the build scripts are ready to be run, the Makefile can be
203 created. Create an empty directory (for example "mkdir work") and cd
204 to that directory. Then run ../gen-makefile.sh
205
206 Review the Makefile, and, if all looks sane, start the build by running
207 "make".
208
2094. GENERATED BUILD SCRIPTS ISSUES::
210
211 In this section, known issues with the generated build scripts are
212 discussed. They are due to build procedures and/or BLFS layout
213 particularities that we can't handle. In several cases, editing the
214 build scripts is mandatory.
215 You may also need to insert some build scripts created by you to resolve
216 unhandled dependencies and/or to remove some script installing an unneeded
217 package (unneeded packages may be pulled in the dependency chain, if
218 they occur as an "or" with another package).
219 When there are circular dependencies (only one known in BLFS 8.0 for
220 recommended dependencies), you may need to move around scripts so that they
221 run in the order script-A script-B script-A. This involves copying script-A
222 to another name (using the xxx-a- fields), and possibly renaming the xxx-a-
223 fields of each involved script.
224
225 4.1 BLFS BOOTSCRIPTS::
226
227 Normally, bootscript installation should work. On the other hand, the
228 book does not give instruction for running them, so you might have to
229 manually insert "/etc/init.d/rc.d/<initscript> start" at some place during
230 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. The shipped 'envars.conf' contains a
237 line 'source /etc/profile', which ensures that the proper environment
238 variables are used.
239
240 4.3 PAGES WITH TWO OR MORE PACKAGES::
241
242 For example: sane, poppler, audacious, freetts, which, etc.
243
244 On the pages for those packages, the BLFS book actually has instructions
245 to download and install two or more packages. You must edit the scripts to
246 fix this. A common pitfall is that the variable PACKAGE may be used for
247 several tarballs. Be sure to save the PACKAGE variable to some other
248 name (for example PKG1, PKG2, etc) after each download. The unpacking
249 instructions may need to be repeated for each tarball in turn.
250
251 4.4 XORG7
252
253 The book has special page layouts for the Xorg7 packages. The tool
254 breaks those pages into individual pages for each packages in the linear
255 book. Also, the menu gives the choice to select each package individually.
256
257 To build the whole Xorg7 chapter, select twm. The (recommended)
258 dependency chain brings in the whole set of Xorg packages.
259
260 4.5 PATCHES
261
262 Please, make sure that all scripts have the commands to download/apply
263 the required patches. Due to book layout issues, some patches may be
264 missing (as of BLFS 8.0, all the patches seem to be downloaded).
265
266 4.6 ROOT COMMANDS
267
268 If building as a normal user (the default setting), be sure that all
269 commands that require root privileges are run using sudo. Also make sure
270 necessary root privilege commands are visible in your PATH. Or use
271 the `Defaults secure_path=' in /etc/sudoers.
272
273 For commands necessitating root privileges, the generated scripts wrap
274 them with the construct:
275 sudo -E sh << ROOT_EOF
276 <commands to be executed as root with `$', ``', and `\' escaped>
277 ROOT_EOF
278 The -E switch ensures the whole environment is passed to the
279 commands to be run with root privileges. It is effective only if the
280 /etc/sudoers file contains `Defaults setenv', or SETENV in the user
281 attributes. If you think it is a security issue, you may forbid this
282 flag in /etc/sudoers, but then, you have to un-escape `$' for variables
283 coming from the environment in the instructions.
284 Although this construct is rather strong, it can fail in some corner
285 cases, so carefully review those instructions.
286
287 WARNING: One variable from the environment is not passed through the
288 -E switch, namely PATH. This is because "sudo" always reset the PATH to
289 the default "secure_path". If you need to have the same PATH as the user
290 "root" would have, you may want to add "source /etc/profile" at the
291 beginning of the commands to be executed as root.
292
293 Due to book layout issues, some sudo commands may be missing.
294
295 4.7 OTHERS
296
297 There may be other issues that we are not aware of. If you find
298 any, please report it to <alfs-discuss@linuxfromscratch.org>.
299
Note: See TracBrowser for help on using the repository browser.