aboutsummaryrefslogtreecommitdiff
path: root/docs/install.txt
blob: ba1899cf82fcb743735080b2ff6d95f7e860b798 (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
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
			  ____________________

			   INSTALLATION GUIDE
			  ____________________


These are the step-by-step instructions for installing Carbs Linux. It
can be acquired as plain-text to be viewed offline with a pager from
<https://carbslinux.org/install.txt>.

,----
| curl -sL https://carbslinux.org/install.txt | less
`----

1. Preparing Environment
.. 1. Download
.. 2. Signature verification
.. 3. Extracting the tarball
.. 4. Obtain the chroot helper
2. Chroot
.. 1. Setting up repositories
..... 1. Obtaining from git
..... 2. Obtaining from rsync
..... 3. Making the package manager use the repositories
.. 2. Updating packages
.. 3. Installing packages
.. 4. Essential Software
.. 5. Obtaining the documentation
3. System Configuration
.. 1. Configuring hostname
.. 2. Hosts file
4. Kernel
.. 1. Obtaining the kernel sources
.. 2. Kernel dependencies
.. 3. Building the kernel
5. Making your system bootable
.. 1. Bootloader
..... 1. GRUB BIOS installation
..... 2. GRUB UEFI installation
.. 2. Init scripts
.. 3. Fstab
6. Post-installation
.. 1. KISS repositories


1 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:

  - tar
  - wget
  - xz
  - some form of base utilities (coreutils, sbase, busybox, etc.)

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


1.1 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 `x86_64' with `i686'. We are setting this in a
  URL variable so that we don't have to write it every time.

  ,----
  | wget $URL/carbs-rootfs.tar.xz.sha256
  | sha256sum -c carbs-rootfs.tar.xz.sha256
  `----


1.2 Signature verification
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

  ,----
  | wget $URL/carbs-rootfs.tar.xz.sig
  | gpg --recv-keys FF484BDFEFCEF8FF
  | gpg --verify carbs-rootfs.tar.xz.sig
  `----


1.3 Extracting the tarball
~~~~~~~~~~~~~~~~~~~~~~~~~~

  You will need to extract the tarball to your desired location. For
  partitioning, you can follow [this guide]. This will assume that you
  will be mounting your root partition to `/mnt'.

  ,----
  | mount /dev/sdx1 /mnt
  | tar xf carbs-rootfs.tar.xz -C /mnt
  `----


[this guide] <https://wiki.archlinux.org/index.php/Partitioning>


1.4 Obtain the chroot helper
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  You can obtain the `cpt-chroot' script in order to do a simple chroot
  into your new root filesystem.

  ,----
  | wget https://dl.carbslinux.org/distfiles/cpt-chroot
  | chmod a+x cpt-chroot
  `----


2 Chroot
========

  Chroot into Carbs Linux!

  ,----
  | ./cpt-chroot /mnt
  `----


2.1 Setting up repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Newest tarballs do not come with repositories, so you will need to
  manually obtain them, and set your `CPT_PATH' environment
  variable. Carbs Linux repositories can either be obtained by `git' or
  `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 `git' itself.

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

  ,----
  | mkdir -p $HOME/repos
  `----


2.1.1 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.

  - git://git.carbslinux.org/repository
  - <https://github.com/carbslinux/repository>

  ,----
  | git clone git://git.carbslinux.org/repository $HOME/repos/carbs
  `----


2.1.2 Obtaining from rsync
--------------------------

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

  ,----
  | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
  `----


2.1.3 Making the package manager use the repositories
-----------------------------------------------------

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

  ,----
  | 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
  `----


2.2 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.

  ,----
  | cpt-update && cpt-update
  `----


2.3 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.

  ,----
  | cpt-build   package
  | cpt-install package
  `----


2.4 Essential Software
~~~~~~~~~~~~~~~~~~~~~~

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

  *BOOTLOADERS*

  - efibootmgr
  - grub

  *FILESYSTEMS*

  - e2fsprogs
  - dosfstools
  - ntfs-3g

  *NETWORKING*

  - dhcpcd
  - wpa_supplicant

  *TEXT EDITORS*

  - nano
  - vim
  - neatvi
  - emacs
  - emacs-nox (terminal-only version of emacs)

  *USER SHELLS*

  - bash
  - zsh
  - oksh
  - rc

  *POSIX BASE UTILITIES*

  - busybox
  - sbase
  - coreutils

  *DOCUMENTATION*

  - carbs-docs
  - man-pages
  - man-pages-posix


2.5 Obtaining the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  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.

  ,----
  | # 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
  `----


3 System Configuration
======================

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


3.1 Configuring hostname
~~~~~~~~~~~~~~~~~~~~~~~~

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

  ,----
  | echo your-hostname > /etc/hostname
  `----


3.2 Hosts file
~~~~~~~~~~~~~~

  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.

  ,----
  | 127.0.0.1  localhost.localdomain localhost
  | ::1        localhost.localdomain localhost ip6-localhost
  `----


4 Kernel
========

  Kernel isn't managed under the main repositories, even though you
  could package one for your personal use. Here is an [example kernel
  package], which you will need to reconfigure for your specific setup
  if you want to make use of it.


[example kernel package]
<https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux>

4.1 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.

  ,----
  | # Download the kernel and extract it
  | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz
  | tar xf linux-5.9.1.tar.xz
  | 
  | # Change directory into the kernel sources
  | cd linux-5.9.1
  `----


4.2 Kernel dependencies
~~~~~~~~~~~~~~~~~~~~~~~

  In order to compile the kernel you will need to install some
  dependencies. You will need `libelf', and `bison' to compile the
  kernel. If you want to configure using the menu interface you will
  also need `ncurses'.

  ,----
  | # 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
  `----

  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 [E5ten]. You will need to obtain and apply
  the patch in the kernel source directory.

  ,----
  | wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
  | patch -p1 < kernel-no-perl.patch
  `----


[E5ten] <https://github.com/E5ten>


4.3 Building the kernel
~~~~~~~~~~~~~~~~~~~~~~~

  Next step is configuring and building the kernel. You can check
  Gentoo's [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.

  ,----
  | make menuconfig
  | make
  | install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
  `----


[kernel configuration guide]
<https://wiki.gentoo.org/wiki/Kernel/Configuration>


5 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.


5.1 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).


5.1.1 GRUB BIOS installation
----------------------------

  ,----
  | cpt b grub && cpt i grub
  | grub-install --target=i386-pc /dev/sdX
  | grub-mkconfig -o /boot/grub/grub.cfg
  `----


5.1.2 GRUB UEFI installation
----------------------------

  ,----
  | 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
  `----


5.2 Init scripts
~~~~~~~~~~~~~~~~

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

  ,----
  | cpt b carbs-init && cpt i carbs-init
  `----


5.3 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:

  ,----
  | wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
  | chmod +x genfstab
  | ./genfstab -U /mnt >> /mnt/etc/fstab
  `----


6 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.  You can check the rest of the documentation to
  learn more about the system.


6.1 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.