README 11.4 KB
Newer Older
1
AIF is the Arch Linux Installation Framework.
Dieter Plaetinck's avatar
Dieter Plaetinck committed
2

Dieter Plaetinck's avatar
Dieter Plaetinck committed
3
License:     GPL3. See COPYING.
4
Authors:     Dieter Plaetinck
Dieter Plaetinck's avatar
Dieter Plaetinck committed
5
             Patches from Gerhard Brauer, Matthias Dienstbier, Jud Film, Laszlo Papp and 'tuxce'
6
7
             Quite some code has been taken from the installer project @ http://projects.archlinux.org/?p=installer.git;a=summary
             The main authors/contributors of that project are Judd Vinet, Tobias Powalowski, Simo Leone, Aaron Griffin and Dan McGee
8
9
10
Homepage:    http://github.com/Dieterbe/aif


Dieter Plaetinck's avatar
Dieter Plaetinck committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
** Dependencies **
 - util-linux-ng
 - bash >=4
 - pacman >=3.4
 - coreutils
 - grub
 - grep
 - awk
 - sed
 - libui-sh
Optionally:
 - markdown: to generate the html installation guide
 - cryptsetup: for encryption support
 - lvm2: for LVM support
 - dhcpd: for dhcp networking support
 - e2fsprogs: Ext support
 - jfsutils: JFS support
 - reiserfsprogs: ReiserFS support
 - nilfs-utils: Nilfs2 support
 - xfsprogs: XFS support
 - ntp: setting date with NTP
 - dialog: for ncurses support
33
 - curl: for the aif-report-issues.sh script
34
 - syslinux: for syslinux support
35

36
37
38
39
40
41
42
43
44
45
46
47
48
** Goals **

The goal of this project is to:
1) provide reasonable clean, DRY, modular and maintainable code for the Arch Linux installer
2) provide complete, easily-reusable libraries for disk partitioning, UI, package management, etc
3) provide some sensible default installation methods (eg interative, automatic (prescripted), ..)
4) allow power users to easily override certain aspects of the installation procedures
   or creating customized procedures, leveraging the available code.

The goal of AIF is not (yet) to:
1) provide an installer who detects your stuff and tries to be smart and configures all your stuff.
   If you're interested in this, feel free to build it and I may incorporate it someday.
2) be more fancy then needed
49

50

51
52
53
54
55
** Branches **
-> master: "stable" tree, infrequent updates
-> develop: unstable development tree, which may get rewritten at some points,
   only when things have settled down (every x weeks/months), gets pushed to master
-> optionally: more topic branches which are rewriteable and which come and go
56
57
58

** A bit of history **

59
AIF is based on the old archlinux-installer, but the code has been madly refactored, reorganized, cleaned
60
61
62
63
64
up, improved and in some places replaced.
The initial goal was to build an automated installer with a reusable
backend, but the porting of the userfriendly, interactive installer from /arch/setup quickly became a proof of concept
and even main focus point.  See http://www.nabble.com/Fifa:-Flexible-Installer-Framework-for-Arch-linux-td20256427.html

65
66
arch-installer used to be installed as /arch/setup and /arch/quickinst; wheres AIF adheres to the FHS spec,
but archiso images come with an /arch/setup 1-line script which now just calls aif with the interactive procedure and dialog (ncurses) frontend.
Dieter Plaetinck's avatar
Dieter Plaetinck committed
67

68
** Bug/feature request tracking.  Getting in touch ** 
Dieter Plaetinck's avatar
Dieter Plaetinck committed
69

70
AIF developement happens under the umbrella of the release engineering project of Arch Linux.
Dieter Plaetinck's avatar
Dieter Plaetinck committed
71

72
73
74
- bug tracker:  the Arch Linux bugtracker, "Release Engineering" project, category 'AIF'.
                http://bugs.archlinux.org/toplevel/proj6
- mailing list: http://www.archlinux.org/mailman/listinfo/arch-releng
Dieter Plaetinck's avatar
Dieter Plaetinck committed
75

76
77
78
There are some known issues (see the bugtracker, TODO file and various TODO's in the source code) 
If you encounter issues, please report them on the bugtracker, after checking if they are not reported yet of course.
If you want to get in touch with us, to ask/discuss/.. things, please send to the mailing list.
Dieter Plaetinck's avatar
Dieter Plaetinck committed
79
80


Dieter Plaetinck's avatar
Dieter Plaetinck committed
81

82
** Lingo **
Dieter Plaetinck's avatar
Dieter Plaetinck committed
83

84
85
86
87
88
- procedure = a 'plugin' for aif that controls how the installation advances and how the interaction with the user happens
- lib       = a library for aif with some useful functions (eg lib-pacman handles all pacman related things)
- module    = a bundle that can contain zero or more procedures and libraries.
- profile   = a fancier name for a config file.  some procedures support the use of profiles (eg automatic), others don't (eg interactive)
- partial procedure = a 'mini' procedure that lets the user perform one or more smaller aspects of (or related to) an installation
Dieter Plaetinck's avatar
Dieter Plaetinck committed
89
90


91
** Basic workflow **
92

93
94
95
AIF comes by default with these procedures:
- base:        basic, little-interactivity installation with some common defaults. 
               This procedure is used by the others to inherit from, it is NOT meant to be used directly by end users
96
- interactive: An interactive installation procedure.
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
               Asks you some questions, guides you through an installation
               and even helps you a bit by updating configuration files on the target
               system with your usettings
- automatic:   An automated, deploy-tool-alike procedure.  designed for low-
               to zero interactivity.  uses profiles for configuration of the installation/target system.  
               See /usr/share/aif/examples/ for example profile files.
- partial-configure-network: exposes the network configuration step from the interactive procedure
- partial-disks: Process disk subsystem or do a rollback
- partial-keymap: change your keymap/console font settings.  The benefit of this method over a simple loadkeys is that the interactive procedure will
                  automatically update the rc.conf on the target system with your settings.

You would usually invoke aif like this:
aif -p interactive
aif -p automatic -c <profile file> [-l]
aif -p <custom module name>/<your procedure>
Type `aif -h` or just aif to see more details.



** Packages and file locations: **

The officially supported package is aif, in extra.  There are also
unsupported development git packages in AUR.  See HOWTO

File locations:
122
* aif.sh        -> /sbin/aif
123
124
125
* docs          -> /usr/share/aif/docs
* core module   -> /usr/lib/aif/core
* user modules  -> /usr/lib/aif/user/<module name> (put your own modules here)
126
* runtime files -> /tmp/aif
127
* logs          -> /var/log/aif
128

Dieter Plaetinck's avatar
Dieter Plaetinck committed
129
130
131


** (Internal) Workflow **
132
There is a very basic but powerful workflow defined by variables, phases and workers.
133
Depending on the procedure you choose (or write yourself), these will differ
134
In the code, they are very recognizable and are named like this:
135
 - variable -> var_<FOO>
136
 - phase    -> phase_<bar> (an array in which each element is a worker to be executed, with optionally arguments for that worker)
137
138
139
140
               There are 4 phases: preparation, basics, system, finish. (executed in that order)
 - worker   -> worker_<baz> ( a worker function, called by a phase. implements some specific logic.
               eg runtime_packages, prepare_disks, package_list etc)

141

142
143
You can depend on whatever procedure you like (like core/base), to save
yourself some work (you only need to override a few things)
144
145

Notes:
146
147
 - You don't need to use the concept of phases, for example the interactive procedure doesn't use them.
 - The phases are started by the start_process function.  You can also override this function to take flow control in your own hands (like interactive does) 
148
149
 - you _can_ override _all_ variables and functions in your modules, but you should be able to achieve your goals by
   overriding only the 3 basic things and the start_process function, and only in procedures.
150
 - you _must_ specify a procedure, to avoid errors. take 'interactive' if unsure
151
 - don't edit the base procedure (or any other core item), rather make your own. It's easy!
152
 - you're not supposed to define new phases. just override them. logic goes in workers/libariers
153
154
155
 - workers and phases are pretty regular functions, except that they are invoked through a wrapper (the `execute` function), which tracks the exitcodes
   this allows to get reports at the end of the install showing which steps completed successfully and where things failed.  Other then that, there is nothing
   special about them.  It is even possible to have your workers function as a callback by having library functions invoking them.
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186


** Extending AIF **

*** Modules ***
 -> Modules are the building blocks in aif
 -> user modules are just directories with a 'libs' and 'procedures' subdirectory
    where you can put your customized.. guess what.  See 'file locations'
 -> The core module comes by default and contains everything 99% of the users will need. 
    Don't name your custom module 'core' (it will be ignored).
    Don't call it http either, because you can specify 'http://some/path/to/a/procedure',
    aif will download that procedure and execute it (and the module will be 'http')

*** Procedures ***
 -> You can take a procedure, copy it, modify it and call it. that's fine.
 -> You can also write a new one from scratch, inheriting some other procedure using
    the depend_procedure call and just overriding what you need.

 -> Commandline arguments are parsed by aif.sh but you can extend/override it's
    behaviour by overriding $var_OPTS_STRING and the process_vars variable.
    Also, you do not _have_ to use the variables they set (eg arg_ui_type).  You
    usually will set defaults in the configure worker and override with
    arguments passed by the user (eg to use cli mode unless user wants dia)

*** Libraries **
 -> If you have logic that may be reusable by several procedures, consider
    putting the functions in a library so you, and others can easily use it.

*** Profiles ***
 -> You can take a profile and modify it
 -> you can also use the depend_profile call and just override what you need.
187

188

189
190
191
192
Note that if you load a module and a library has the same function names as
the core module, it will override the functions from core.
This means you can 'inject' new backend code into core procedures, but you
can also write your own procedures that use your own, or the core libraries.
193
194
195
If you load a module, you actually load it's libraries, not it's procedures!
Procedures are only loaded when needed (because you request them because
of dependencies)
196
197

If you need a library from another user contributed module, execute
198
'depend_module <modulename>' for each module.  This way you load all the
199
200
201
libs of that module (not the procedures, use depend_procedure for that. 
keep in mind that the position of the depend_procedure statement defines
where your variables/functions might be overridden...)
202
203
204
205
206
207
(very basic dependencies, no version checking etc)

You can specify a core procedure on the command line by specifying
'<procedure_name>', to specify a user contriubuted procedure, specify
'<module_name>/<procedure_name>'

208
209


Dieter Plaetinck's avatar
Dieter Plaetinck committed
210
** Contributing **
211

Dieter Plaetinck's avatar
Dieter Plaetinck committed
212
Install a VM (I use virtualbox-ose, works fine), make a vm, boot the install cd and just follow the HOWTO.
Dieter Plaetinck's avatar
Dieter Plaetinck committed
213
It's probably easiest if you set up your own git clone that you can easily
Dieter Plaetinck's avatar
Dieter Plaetinck committed
214
acces from the VM (You can open a github account and fork my code).
215
You can edit on the cd itself, but given the low resolution of the VM, you'll probably edit on your pc, commit, push to github
Dieter Plaetinck's avatar
Dieter Plaetinck committed
216
and pull from the clone on the cd.
217
If you want to do debugging, just call the debug function and export DEBUG=1
Dieter Plaetinck's avatar
Dieter Plaetinck committed
218
before calling the scripts. (or pass -d)
Dieter Plaetinck's avatar
Dieter Plaetinck committed
219
220
221
Keep in mind there are 3 kinds of variables.  Those that affect/belong to
the runtime (install cd live environment), target (affects/belongs to the
target installation) and TMP (everything in between or extra). Variablenames
222
223
should have _TARGET or _TMP suffixes or none for runtime.  (That's the
theory, it isn't always the case like that now, I need to do more refactoring)
224
225
226
227

** Test suite **

AIF also has a (WIP) test-suited. the source is the documentation.
228
229
230
231
232

** Reporting issues / getting help **

Run the aif-report-issues.sh script, which will submit valuable (for debugging)
info to a public pastebin, you can then give the url to the people who need to help you