README.rst 3.79 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
=======
archiso
=======

The archiso project features scripts and configuration templates to build installation media (*.iso* images) for BIOS
and UEFI based systems on the x86_64 architecture.
Currently creating the images is only supported on Arch Linux.

Requirements
============

The following packages need to be installed to be able to create an image with the included scripts:

* arch-install-scripts
* dosfstools
* e2fsprogs
* libisoburn
18
* mtools
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
* squashfs-tools

For running the images in a virtualized test environment the following packages are required:

* edk2-ovmf
* qemu

For linting the shell scripts the following package is required:

* shellcheck

Profiles
========

Archiso comes with two profiles: **baseline** and **releng**. While both can serve as starting points for creating
custom live media, **releng** is used to create the monthly installation medium.
They can be found below `configs/baseline/ <configs/baseline/>`_  and `configs/releng/ <configs/releng/>`_
36
(respectively). Both profiles are defined by files to be placed into overlays (e.g. *airootfs* -> *the image's /*).
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

Create images
=============

Usually the archiso tools are installed as a package. However, it is also possible to clone this repository and create
images without installing archiso system-wide.

As filesystems are created and various mount actions have to be done when creating an image, **root** is required to run
the scripts.

When archiso is installed system-wide and the modification of a profile is desired, it is necessary to copy it to a
writeable location, as */usr/share/archiso* is tracked by the package manager and only writeable by root (changes will
be lost on update).

The examples below will assume an unmodified profile in a system location (unless noted otherwise).

53
It is advised to consult the help output of **mkarchiso**:
54
55
56

  .. code:: bash

57
    mkarchiso -h
58
59
60
61
62
63

Create images with packaged archiso
-----------------------------------

  .. code:: bash

64
    mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
65
66
67
68

Create images with local clone
------------------------------

69
Clone this repository and run:
70
71
72

  .. code:: bash

73
    ./archiso/mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
74
75
76
77
78

Testing
=======

The convenience script **run_archiso** is provided to boot into the medium using qemu.
79
It is advised to consult its help output:
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

  .. code:: bash

    run_archiso -h

Run the following to boot the iso using BIOS:

  .. code:: bash

    run_archiso -i path/to/an/arch.iso

Run the following to boot the iso using UEFI:

  .. code:: bash

95
    run_archiso -u -i path/to/an/arch.iso
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

The script can of course also be executed from this repository:


  .. code:: bash

    ./scripts/run_archiso.sh -i path/to/an/arch.iso

Installation
============

To install archiso system-wide use the included **Makefile**:

  .. code:: bash

    make install

113
114
115
116
117
118
Optionally install archiso's mkinitcpio hooks:

  .. code:: bash

    make install-initcpio

David Runge's avatar
David Runge committed
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
Contribute
==========

Development of archiso takes place on Arch Linux' Gitlab: https://gitlab.archlinux.org/archlinux/archiso

Please read our distribution-wide `Code of Conduct <https://wiki.archlinux.org/index.php/Code_of_conduct>`_ before
contributing, to understand what actions will and will not be tolerated.

Read our `contributing guide <CONTRIBUTING.rst>`_ to learn more about how to provide fixes or improvements for the code
base.

Discussion around archiso takes place on the `arch-releng mailing list
<https://lists.archlinux.org/listinfo/arch-releng>`_ and in `#archlinux-releng
<ircs://chat.freenode.net/archlinux-releng>`_ on `freenode.net <https://freenode.net/>`_.

All past and present authors of archiso are listed in `AUTHORS <AUTHORS.rst>`_.

136
137
138
139
License
=======

Archiso is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).