source: README.CUSTOM@ 50cf934

ablfs-more legacy trunk
Last change on this file since 50cf934 was 2257bd7, checked in by Pierre Labastie <pierre.labastie@…>, 3 years ago

Update and fix documentation of custom tools

  • Property mode set to 100644
File size: 9.7 KB
Line 
1#
2# $Id$
3#
4 HOW TO ADD CUSTOM SCRIPTS TO THE JHALFS MAKEFILE
5
6
7 Normally JHALFS creates a Makefile containing only those scripts found in
8the {,B,C,H}LFS books. An automated construction tool cannot predict the
9needs of every individual and requests are made "Can you add xxxx package".
10Rather than adding numerous package scripts and switches for each request it
11was easier to add a tool for the user(s) to code their own package needs.
12
13 There are two areas that can be customized: how the base system is built
14and what additional configurations and packages your hardware requires to be
15able to boot and run. Each of those areas are handled in a different way.
16
17
18
19 BASE SYSTEM CUSTOMIZATION
20
21 There are two ways to alter how the base system will be built:
22
23 - Using a working copy of the book sources and editing the XML files.
24 This is the way used by book editors to test packages upgrades,
25 command changes, build order changes. etc.
26
27 This method requires you know very well the book sources and what
28 files need be edited. It will not be discussed here.
29
30 - Editing the generated build scripts to make any change you want.
31 This is the method discussed below.
32
33
34 EDITING THE BASE SCRIPTS
35
36 To begin with, the build scripts should be generated with book defaults. To
37do that, configure jhalfs activating any option you want included, but do not
38select "Run the Makefile" option.
39
40 Under the ${BUILD_DIR}/${SCRIPT_ROOT}/${PROGNAME}-commands directory
41(using the defaults values to do an LFS build, that directory name is
42/mnt/build_dir/jhalfs/lfs-commands) you will find the default build scripts.
43
44 If all you want is modify, add, or remove some command from a package
45installation, for example to change its ./configure line, just edit the related
46script. If changing or adding a patch, be sure to copy the new patch to the
47${BUILD_DIR}/sources directory. When done, run 'make' from inside the
48${BUILD_DIR}/${SCRIPT_ROOT} directory.
49
50
51 REPLACING OR INSERTING PACKAGES AND CHANGING BUILD ORDER
52
53 To remove a package from the system, just remove its script(s).
54
55 To change the version of some package, or to build a newer or older version
56than that in the book, edit ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list to
57change its tarball name and place the new tarball in the ${BUILD_DIR}/sources
58directory.
59
60 To replace a package by an equivalent one, rename the replaced package script
61to reflect the new package name (for example, 102-man-db -> 102-man), edit the
62script to make the required commands changes, place the new tarball in the
63${BUILD_DIR}/sources directory, and edit ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list
64file to replace the removed package tarball name by the new package tarball
65name.
66
67 To change the build order, rename the scripts changing the first 3-digits
68string until they are sorted in the way you want.
69
70 To insert a new package, for example to build Cracklib in order to build
71Shadow with Cracklib support, you should first decide before what package it
72needs to be installed, in this example 107-shadow. Then create a new script
73containing the needed commands, using an existing one as template, and name it
74with the same 3-digits string used for that mentioned default package, but
75adding another 1-digit string. In our example, the new script to build Cracklib
76before Shadow will be named 107-1-cracklib. This naming scheme allows inserting
77up to 10 scripts before each of the existing scripts. Place the tarball for
78the new package and required patches, if any, in ${BUILD_DIR}/sources and edit
79${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list to add the tarball name for that
80package.
81
82 When ready, launch again the jhalfs configuration interface. Make sure that
83exactly the same options are selected as when generating the default build
84scripts. Be sure that "Rebuild files" is unselected and select "Run the
85Makefile" if you want. Then select "Rebuild the Makefile". This will create a
86new Makefile based on the changes you made to the build scripts.
87
88
89 ADDING POST-SYSTEM BUILD CONFIGURATION FILES AND EXTRA PACKAGES
90
91 The installation of BLFS packages is handled via blfs-tool and activated
92when you select the appropriate menu option. See README and README.BLFS for
93more info.
94
95 The feature described below was added so users could install remaining
96configuration files, build the packages necessary to access the Internet
97or to support specific hardware, or to install basic utilities that are
98needed from the beginning, and was not intended to replace the BLFS
99install system.
100
101 LAYOUT
102 A new directory has been added to JHALFS tree which contains the
103configuration scripts and a few examples. A switch has been added to the
104configuration file which enables/disables the inclusion of custom scripts.
105
106 custom
107 /config <-- where to put your scripts.
108 /examples <-- a few example scripts
109 /examples_CLFS-E <-- example scripts for CLFS-Embedded
110 template <-- ALL scripts MUST look like this
111
112
113
114 NOTE::: You are responsible for including all dependencies and ensuring they
115 are built in the right order.
116
117 1. To add a package to the final JHALFS Makefile you must first create a file
118 in the custom/config directory.
119 **All config files MUST follow the naming convention, xxx-PKG, where xxx
120 is the order number and PKG is the name of the package. The file naming
121 format is important as it defines the build order. The example shown
122 below has an order number 950 and log files will list in alphabetical
123 order in the /logs directory after blfs-tools scripts.
124 The simplest method is to copy the template file into the config directory
125 and rename it.
126
127 2. Populate the variables with the necessary values.
128 Variable function is self explanatory. PATCH variables must be
129 numbered, starting at PATCH1 (up to PATCH10). If the md5 checksum value
130 is known, it can be added after the URL as in (quotes needed):
131 PATCH1="http://patch-host/patch-path xxxxxxx..."
132
133 3. Build commands
134 If the package you want to include is found in the BLFS
135 book then you only need to copy/paste the commands between the xEOFx
136 text, otherwise you will need to define the commands yourself.
137 NOTE::: This script you just created is not usable directly but contains
138 all the information necessary for jhalfs to create a build script
139 and an entry in the jhalfs Makefile.
140
141 4. As mentioned previously the build order is dictated by the 3 digit number
142 in the file name. If a package has dependencies it must be numerically
143 larger than the dependency files.
144 e.g. The package mc has glib as a dependency, so the build order is:
145 950-glib
146 951-mc
147
148 5. A config file for BLFS-bootscripts is already created as 999-blfs_bootscripts.
149 If a package requires a bootscript to be installed add the cmd to this
150 file and NOT in the package script. The gpm script is included as an
151 example of patch file and the need for a blfs bootscript.
152
153
154 EXAMPLES
155
156 Other examples can be found in custom/examples. They are dated and
157 unmaintained, but can be useful for creating your own scripts.
158
159 :::NOTICE:::
160 The following examples are for use with LFS and are not applicable to any
161of the CLFS-sysroot or CLFS-Embedded books. The directory examples_CLFS-E
162contains code extracted from Beyond CLFS-embedded. Any packages you chose to
163add should honour the DESTDIR=${CLFS} switch or equivalent.
164
165
166#--------- GLIB example -----------
167
168 #
169 # Filename syntax xxx-PKG ie. 950-glibc
170 # Create a file in the custom/config directory
171 # Populate the file using the following script as an example
172 #
173
174PKG="glib"
175PKG_VERSION="1.2.10"
176PKG_FILE="glib-1.2.10.tar.gz"
177URL="http://gd.tuwien.ac.at/graphics/gimp/gtk/v1.2/${PKG_FILE}"
178MD5="6fe30dad87c77b91b632def29dd69ef9"
179
180 # The following code removes previously defined PATCHx variables
181for i in PATCH{1..10}; do
182 unset $i
183done
184 # Patches are named PATCH[1..10]
185 # This information is used to download the patch only
186PATCH1="http://www.linuxfromscratch.org/patches/blfs/svn/glib-1.2.10-gcc34-1.patch 0077a1cce5e8a2231ac5a9b08c6263ba"
187
188
189 # NOTE::
190 # The convoluted scheme used to write out a temporary file is
191 # a work-around for embedded single and double quotes.
192
193( cat << "xEOFx"
194
195patch -Np1 -i ../glib-1.2.10-gcc34-1.patch &&
196./configure --prefix=/usr &&
197make
198make install &&
199chmod -v 755 /usr/lib/libgmodule-1.2.so.0.0.10
200
201xEOFx
202) > tmp
203
204
205#--------- GPM example -----------
206
207
208PKG="gpm"
209PKG_VERSION="1.20.1"
210PKG_FILE="gpm-1.20.1.tar.bz2"
211URL="ftp://arcana.linux.it/pub/gpm/gpm-1.20.1.tar.bz2"
212MD5="2c63e827d755527950d9d13fe3d87692"
213for i in PATCH{1..10}; do
214 unset $i
215done
216PATCH1=" http://www.linuxfromscratch.org/patches/blfs/svn/gpm-1.20.1-segfault-1.patch"
217PATCH2=" http://www.linuxfromscratch.org/patches/blfs/svn/gpm-1.20.1-silent-1.patch"
218
219
220( cat << "xEOFx"
221
222patch -Np1 -i ../gpm-1.20.1-segfault-1.patch &&
223patch -Np1 -i ../gpm-1.20.1-silent-1.patch &&
224./configure --prefix=/usr --sysconfdir=/etc &&
225LDFLAGS="-lm" make
226
227make install &&
228cp -v conf/gpm-root.conf /etc &&
229ldconfig
230
231# The normal cmd to install the boot script for gpm
232# --- PUT THIS CMD INSIDE 999-blfs_bootscripts
233#make install-gpm
234
235cat > /etc/sysconfig/mouse << "EOF"
236# Begin /etc/sysconfig/mouse
237
238MDEVICE="/dev/psaux"
239PROTOCOL="imps2"
240GPMOPTS=""
241
242# End /etc/sysconfig/mouse
243EOF
244
245xEOFx
246) > tmp
247
248
249#--------- CMDS ONLY example -----------
250 # This is an example of a self contained cmd script
251 # There are no referenced to a package or package dir.
252 # This method is useful for creating user files/profiles/etc
253 # at build time.
254
255
256PKG=""
257PKG_VERSION=""
258PKG_FILE=""
259URL=""
260MD5=""
261for i in PATCH{1..10}; do
262 unset $i
263done
264PATCH1=""
265
266
267( cat << "xEOFx"
268
269echo "JUST A USELESS TRACE"
270
271xEOFx
272) > tmp
Note: See TracBrowser for help on using the repository browser.