aboutsummaryrefslogtreecommitdiff
path: root/install.texi
blob: 37e8bb3b772921762680d0475cc7c93f72d582f4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
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
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
@node Installation
@chapter Installation

These are the step-by-step instructions for installing Carbs Linux.

@ifhtml
The instructions can also be found plaintext on
@url{https://carbslinux.org/docs/install.txt}
@end ifhtml

@menu
* Preparing Environment::        Getting ready to chroot
* Chroot::                       Going inside your new system
* System Configuration::         Customizing for your personal use
* Kernel::                       Compiling your own kernel
* Making your system bootable::  Installing init and bootloader
* Post-installation::            Acquiring more packages and repositories
@end menu

@node Preparing Environment
@section Preparing Environment
To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you
can obtain a Gentoo or Void Linux live image. You can follow their instructions
to boot and setup your network.

You will need the following programs in order to install Carbs Linux:
@itemize
@item
tar
@item
wget
@item
xz
@item
some form of base utilities (coreutils, sbase, busybox, etc.)
@end itemize

Rest of these instructions will assume that you have set all of these up, and
will continue on that point.

@subsection Download

First, we need to download the rootfs tarball. You can do the following in order
to obtain the rootfs. If you are using an i686 machine, replace the @code{x86_64}
with @code{i686}. We are setting this in a URL variable so that we don't have to
write it every time.

@example
$ URL=https://dl.carbslinux.org/releases/x86_64
$ wget $URL/carbs-rootfs.tar.xz
@end example

We can then check the integrity of the tarball and do a signature verification.
Even thought these are optional, they are highly recommended.

@subsection Check the integrity of the tarball (Recommended)

All of the releases are saved in a single file named @file{sha256sums.txt}, but the
latest release is saved on @file{carbs-rootfs.tar.xz.sha256}. You can acquire and
verify the tarball.

@example
$ wget $URL/carbs-rootfs.tar.xz.sha256
$ sha256sum -c carbs-rootfs.tar.xz.sha256
@end example

@subsection Verify the signature

It is highly recommended to verify the signature of the tarball. You will need
GPG for this.

@example
$ wget $URL/carbs-rootfs.tar.xz.sig
$ gpg --recv-keys FF484BDFEFCEF8FF
$ gpg --verify carbs-rootfs.tar.xz.sig
@end example

@subsection Extracting the tarball

You will need to extract the tarball to your desired location. For partitioning,
you can follow @url{https://wiki.archlinux.org/index.php/Partitioning, this guide}.
This will assume that you will be mounting your root partition to @file{/mnt}.

@example
$ mount /dev/sdx1 /mnt
$ tar xf carbs-rootfs.tar.xz -C /mnt
@end example

@subsection Obtain the chroot helper

You can obtain the @command{cpt-chroot} script in order to do a simple chroot into
your new root filesystem.

@example
$ wget https://dl.carbslinux.org/distfiles/cpt-chroot
$ chmod a+x cpt-chroot
@end example

@node Chroot
@section Chroot

Chroot into Carbs Linux!

@example
$ ./cpt-chroot /mnt
@end example

@subsection Setting up repositories

Newest tarballs do not come with repositories, so you will need to manually
obtain them, and set your @env{CPT_PATH} environment variable. Carbs Linux
repositories can either be obtained by @command{git} or @command{rsync}.
While rsync repositories are overall faster and smaller, git offers the whole
history of the repository and a means to manipulate your repository as you like
it. If you want to obtain the git repository, you will need to install
@command{git} itself.

The following guide will assume that you put the repositories into
@file{~/repos/} directory, but you can put the repositories into any directory
you want. So go ahead and create that directory:

@example
$ mkdir -p $HOME/repos
@end example

@subsubsection Obtaining from rsync

Carbs Linux rsync repositories live in @url{rsync://carbslinux.org/repo}. In
order to obtain it, run the following:

@example
$ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
@end example

@subsubsection Obtaining from git

Carbs Linux git repositories can be found both from the main server and GitHub
(mirror). Here are both their repository links. You can clone any of them.

@itemize
@item
@url{git://git.carbslinux.org/repository}
@item
@url{https://github.com/carbslinux/repository}
@end itemize

@example
$ git clone git://git.carbslinux.org/repository $HOME/repos/carbs
@end example

@subsubsection Making the package manager use the repositories

In your shell's configuration file, or in your @file{~/.profile} file, add the
following lines:

@example
export CPT_PATH=''
CPT_PATH=$CPT_PATH:$HOME/repos/carbs/core
CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra
CPT_PATH=$CPT_PATH:$HOME/repos/carbs/xorg
CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community
export CPT_PATH
@end example

@subsection Updating packages

It is good practice to make sure your system is up to date, especially before
building new packages. If there is an update for the package manager you will
need to update twice.

@example
$ cpt update
@end example

@subsection Installing packages

Since you are operating on a really small base, you might need to build and
install new programs to extend the functionality of your system. In order to
build and install packages new packages in Carbs, you need to execute the
following. ``Package'' is not actually a package and is given as an example.

@example
$ cpt build package
$ cpt install package
@end example

@subsection Essential Software

Here is a list of software that you might want to have on your system.

BOOTLOADERS
@itemize
@item
efibootmgr
@item
grub
@end itemize
FILESYSTEMS
@itemize
@item
e2fsprogs
@item
dosfstools
@item
ntfs-3g
@end itemize
NETWORKING
@itemize
@item
dhcpcd
@item
wpa_supplicant
@end itemize
TEXT EDITORS
@itemize
@item
nano
@item
vim
@item
neatvi
@item
nvi
@item
emacs
@item
emacs-nox (terminal-only version of emacs)
@end itemize
USER SHELLS
@itemize
@item
bash
@item
zsh
@item
dash
@item
oksh
@item
rc
@end itemize
POSIX BASE UTILITIES
@itemize
@item
busybox
@item
sbase
@item
coreutils
@end itemize
DOCUMENTATION
@itemize
@item
carbs-docs
@item
man-pages
@item
man-pages-posix
@end itemize

@subsection Obtaining the documentation (optional)

All the documentation for Carbs Linux can be found on a single info manual to be
viewed offline. You can obtain texinfo or the info (standalone) package in order
to view the documentation.

@example
Install the documentation.
$ cpt b carbs-docs && cpt i carbs-docs

Install either texinfo or the info package. We will be installing standalone info
as it doesn't need perl.
$ cpt b info && cpt i info

You can then run info and navigate through the documentation.
$ info carbslinux
@end example

@node System Configuration
@section System Configuration

After you have finished installing some extra packages, you can configure your
system to your liking.

@subsection Configuring hostname (recommended)

You might want to add a hostname, especially in a networked environment. Your
hostname will default to 'carbslinux' unless you set this.

@example
$ echo your-hostname > /etc/hostname
@end example

@subsection Setting up hosts file (optional)

You can edit your /etc/hosts file, which is the static lookup table for host
names. By default, there are two entries for localhost which are OKAY. You can
replace the 'localhost' part of these entries to your hostname.

@example
127.0.0.1  localhost.localdomain localhost
::1        localhost.localdomain localhost ip6-localhost
@end example

@node Kernel
@section Kernel

Kernel isn't managed under the main repositories, even though you could package
one for your personal use. Here is an @url{https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux, example kernel package},
which you will need to reconfigure for your specific setup if you want to make
use of it.

@subsection Obtaining the kernel sources

You can visit the https://kernel.org website to choose a kernel that you want
to install. Though only the latest stable and longterm (LTS) versions are
supported.

@example
Download the kernel and extract it
$ wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.7.6.tar.xz
$ tar xf linux-5.7.6.tar.xz

Change directory into the kernel sources
$ cd linux-5.7.6
@end example

@subsection Installing dependencies

In order to compile the kernel you will need to install some dependencies. You
will need @command{libelf} to compile the kernel. If you want to configure using the menu
interface you will also need @command{ncurses}.

@example
The package manager asks to install if you are building more than one package,
so no need to run 'cpt i ...'
$ cpt b libelf ncurses
@end example

In the vanilla kernel sources, you need perl to compile the kernel, but it can
be easily patched out. You will need to apply the following patch. Patch was
written by @url{https://github.com/E5ten, E5ten}. You will need to obtain and
apply the patch in the kernel source directory.

@example
$ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
$ patch -p1 < kernel-no-perl.patch
@end example

@subsection Compiling the kernel

Next step is configuring and building the kernel. You can check Gentoo's @url{https://wiki.gentoo.org/wiki/Kernel/Configuration, kernel configuration guide}
to learn more about the matter. Overall, Gentoo Wiki is a good place to learn
about configuration according to your hardware. The following will assume a
monolithic kernel.

@example
$ make menuconfig
$ make
$ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
@end example

@node Making your system bootable
@section Making your system bootable

In order to be able to boot your fresh system, wou will need an init-daemon,
init-scripts and a bootloader. The init daemon is already provided by busybox,
but you can optionally change it.

@subsection Installing a bootloader

In the main repository, there is efibootmgr and grub to serve as bootloaders.
efibootmgr can be used as a standalone bootloader, or can be used to install
grub in a UEFI environment. efibootmgr is needed unless you are using a device
without UEFI support (or you really want to use BIOS for a reason).

GRUB BIOS installation

@example
$ cpt b grub && cpt i grub
$ grub-install --target=i386-pc /dev/sdX
$ grub-mkconfig -o /boot/grub/grub.cfg
@end example

GRUB UEFI installation

@example
$ cpt b efibootmgr && cpt i efibootmgr
$ cpt b grub && cpt i grub

$ grub-install --target=x86_64-efi \
               --efi-directory=esp \
               --bootloader-id=CarbsLinux

$ grub-mkconfig -o /boot/grub/grub.cfg
@end example

@subsection Installing init scripts

Only thing left to do is installing the init-scripts, and now you are almost
ready to boot your system!

@example
$ cpt b carbs-init && cpt i carbs-init
@end example

@subsection Generating fstab

You can now manually edit your fstab entry, or you can use the genfstab tool.
If you want to use the tool, exit the chroot and run the following:

@example
$ wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
$ chmod +x genfstab
$ ./genfstab -U /mnt >> /mnt/etc/fstab
@end example

@node Post-installation
@section Post-installation

The base installation is now complete, you can now fine tune your system
according to your needs. Rest of these instructions are completely optional.

@subsection Acquiring kiss repositories

While not 100% compatible with cpt, you can use kiss repositories in your
system the same way you are using the distribution repositories. Here is an
example for the KISS Linux Community repository.

@example
$ git clone https://github.com/kisslinux/community $HOME/repos/kiss-community
$ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community
@end example

NOTE: There are lots of packages on the KISS community repository that are also
on Carbs Linux main repository. I would advise giving lower priority to the KISS
community repository as it may affect other packages that you might install.