/[gentoo]/xml/htdocs/doc/en/gentoo-freebsd.xml
Gentoo

Contents of /xml/htdocs/doc/en/gentoo-freebsd.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.16 - (show annotations) (download) (as text)
Thu Mar 30 08:41:57 2006 UTC (8 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.15: +7 -7 lines
File MIME type: application/xml
Commit fixes mentioned on #127477, this time saving the file before committing

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-freebsd.xml,v 1.15 2006/03/28 10:30:14 neysx Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/en/gentoo-freebsd.xml">
6 <title>A short guide to Gentoo/FreeBSD</title>
7
8 <author title="Author">
9 <mail link="ignacio.arquelatour@gmail.com">Ignacio Arque-Latour</mail>
10 </author>
11 <author title="Author">
12 <mail link="citizen428@gentoo.org">Michael Kohl</mail>
13 </author>
14 <author title="Author">
15 <mail link="angusyoung@gentoo.org">Otavio R. Piske</mail>
16 </author>
17 <author title="Author">
18 <mail link="ka0ttic@gentoo.org">Aaron Walker</mail>
19 </author>
20
21 <abstract>
22 This document gives some general information on FreeBSD, as well as
23 installation instructions for Gentoo/FreeBSD. It also includes some reference
24 for people interested in helping out with development.
25 </abstract>
26
27 <!-- The content of this document is licensed under the CC-BY-SA license -->
28 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29 <license/>
30
31 <version>2.3</version>
32 <date>2006-03-24</date>
33
34 <chapter>
35 <title>Introduction to FreeBSD</title>
36 <section>
37 <title>What is FreeBSD?</title>
38 <body>
39
40 <p>
41 <uri link="http://www.freebsd.org/">FreeBSD</uri> is a free (<uri
42 link="http://www.freebsd.org/copyright/freebsd-license.html">license</uri>)
43 Unix-like operating system. Back in 1993 when development of <uri
44 link="http://www.386bsd.org/">386BSD</uri> stopped, two projects were born:
45 <uri link="http://www.netbsd.org/">NetBSD</uri>, commonly known to run on a
46 huge number of architetures, and FreeBSD which supports the x86, amd64, ia64,
47 sparc64 and alpha platforms.FreeBSD is renowned for its stability, performance
48 and security, thus being used from small to huge companies all over the world.
49 FreeBSD's current production release version is 6.0, which is also used as the
50 foundation for the Gentoo/FreeBSD project. The previous 5.x branch is being
51 continued by the FreeBSD project as a service release, but is no more worked on by
52 the Gentoo/FreeBSD developers.
53 </p>
54
55 </body>
56 </section>
57 <section>
58 <title>What is Gentoo/FreeBSD?</title>
59 <body>
60
61 <p>
62 <uri link="/proj/en/gentoo-alt/bsd/fbsd/">Gentoo/FreeBSD</uri> is a subproject of the
63 <uri link="/proj/en/gentoo-alt/">Gentoo/Alt project</uri>, with the goal of providing
64 a fully-capable FreeBSD operating system featuring the design sensibilities known from
65 Gentoo Linux, like the init system and the portage package management system.
66 </p>
67
68 </body>
69 </section>
70 <section>
71 <title>FreeBSD and Linux</title>
72 <body>
73
74 <p>
75 Users migrating from Linux to FreeBSD commonly consider the two operating
76 systems "almost the same". In fact, FreeBSD really shares a lot of similarities
77 with Linux distributions in general. Nevertheless, it has some key differences
78 that are worth noting:
79 </p>
80
81 <ul>
82 <li>
83 Contrary to Linux, which actually only refers to the kernel, FreeBSD is a
84 complete operating system, consisting of a C library, userland tools and
85 much more. This development approach makes the overall system very
86 consistent.
87 </li>
88 <li>
89 Contrary to the Linux kernel, FreeBSD development is not led by one person,
90 but instead managed by a small group of people called the <uri
91 link="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/staff-core.html">Core
92 Team</uri>.
93 </li>
94 </ul>
95
96 <p>
97 Besides, FreeBSD also has some technical differences which set it apart
98 from Linux. Some of them are very important to know, even if you don't plan on
99 joining the Gentoo/FreeBSD development effort:
100 </p>
101
102 <ul>
103 <li>
104 To get run-time dynamic linking functions like <c>dlopen()</c>, programs do
105 not need to be linked against libdl like on GNU/Linux. Instead they are
106 linked against libc.
107 </li>
108 <li>
109 FreeBSD doesn't have an official tool for kernel compilation, thus you'll
110 have to resolve feature dependencies on your own.
111 </li>
112 <li>
113 FreeBSD uses UFS/UFS-2 as its filesystems and has no official support for
114 e.g. ReiserFS or XFS. However, there are projects for adding read-only
115 support for these filesystems. Accessing ext2/ext3 partitions is already
116 possible, but you cannot install your system on them.
117 </li>
118 </ul>
119
120 </body>
121 </section>
122 </chapter>
123
124 <chapter>
125 <title>Installing Gentoo/FreeBSD</title>
126 <section>
127 <title>Installation instructions</title>
128 <body>
129
130 <p>
131 After this short introduction, it's about time to finally install
132 Gentoo/FreeBSD. Unfortunately, we currently lack our own installation media, so
133 you have to choose between two alternative installation methods. The first
134 would be to use an existing FreeBSD installation to partition your hard drive
135 and use it as a base for installing Gentoo/FreeBSD. Alternatively, you can also
136 use the excellent <uri link="http://www.freesbie.org/">FreeSBIE LiveCD</uri> as
137 an installation medium for Gentoo/FreeBSD.
138 </p>
139
140 <note>
141 If you are intending to use FreeSBIE for installing Gentoo/FreeBSD, please make
142 sure to use a version based on FreeBSD 6.0! Experimental versions can be downloaded
143 from <uri link="http://torrent.freesbie.org/">FreeSBIE's Bittorrent tracker</uri> and
144 version 20060118 has been tested to work for the purposes described in this document.
145 </note>
146
147 <p>
148 Before you can begin with the installation, you have to setup a hard disk for
149 use with Gentoo/FreeBSD. This can either be done via <c>sysinstall</c>
150 (available from a current FreeBSD installation as well as from within FreeSBIE)
151 or by manually using the commands <c>fdisk</c>, <c>disklabel</c> and <c>newfs</c>.
152 If you have never set up a FreeBSD system before, <c>sysinstall</c> may be the
153 better option for you. In that case make sure that you don't use the sysinstall
154 launched by FreeBSD's or FreeSBIE's installers, but use the following command instead:
155 </p>
156
157 <pre caption="Partitioning with sysinstall">
158 # <i>sysinstall diskPartitionEditor diskPartitionWrite diskLabelEditor diskLabelCommit</i>
159 </pre>
160
161 <p>
162 If you face difficulties
163 while partitioning or formatting your hard disks, have a look at the great
164 <uri link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/">FreeBSD
165 Handbook</uri> or hop onto <c>#gentoo-bsd</c> on the Freenode IRC server.
166 </p>
167
168 <p>
169 Once you're done setting up your disks, you have to create a mount point for
170 your Gentoo/FreeBSD installation and mount all the necessary partitions.
171 </p>
172
173 <pre caption="Creating a mount point and mounting partitions">
174 # <i>mkdir /mnt/gentoo</i>
175 <comment>(Replace X with the correct numbers for your hard disk.)</comment>
176 # <i>mount /dev/adXsXa /mnt/gentoo</i>
177 </pre>
178
179 <p>
180 If you're using the FreeSBIE LiveCD and you already had an UFS partition on
181 your hard disk, it has already been mounted read-only to <path>/mnt/ufs.1</path>.
182 If you want to use that location for your installation, you'll have to remount it
183 in read-write mode:
184 </p>
185
186 <pre caption="Remounting a partition in read-write mode">
187 # <i>mount -u -o rw /mnt/ufs.1</i>
188 </pre>
189
190
191 <p>
192 Now that you have mounted the target partition, it is time to fetch and unpack
193 a stage3 tarball.
194 </p>
195
196 <pre caption="Obtaining and unpacking a stage3 tarball">
197 # <i>cd /mnt/gentoo/</i>
198 <comment>(Any other Gentoo mirror which includes the experimental/ directory will also work.)</comment>
199 # <i>wget http://gentoo.osuosl.org/experimental/x86/freebsd/stages/gentoo-freebsd-6.0-stage-20060221.tar.bz2</i>
200 # <i>tar -jxvpf gentoo-freebsd-6.0-stage-20060221</i>
201 <comment>(You can delete the tarball with the following command if you want to.)</comment>
202 # <i>rm gentoo-freebsd-6.0-stage-20060221</i>
203 </pre>
204
205 <p>
206 Before chrooting into the newly-extracted stage, you first must obtain an
207 up-to-date copy of the Gentoo/FreeBSD overlay. The easiest way to achieve this
208 is to to get our latest snapshot which you then extract to
209 <path>/mnt/gentoo/usr/local/portage</path>.
210 </p>
211
212 <pre caption="Getting the Gentoo/FreeBSD Portage overlay">
213 # <i>cd /mnt/gentoo/usr/local/portage</i>
214 # <i>wget http://gentoo.osuosl.org/experimental/snapshots/portage-alt-overlay-latest.tar.bz2</i>
215 # <i>tar -xjf portage-alt-overlay-latest.tar.bz2</i>
216 <comment>(You now can safely delete the snapshot with the following command.)</comment>
217 # <i>rm portage-alt-overlay-latest.tar.bz2</i>
218 </pre>
219
220 <p>
221 Alternatively, you can also use Subversion to check out the current version of
222 the overlay. If you are interested in this possibility, please refer to the
223 <uri
224 link="/proj/en/gentoo-alt/contribute/index.xml?part=1&amp;chap=3">Gentoo/ALT
225 overlay documentation</uri>.
226 </p>
227
228 <p>
229 In order for your install to work, you need to mount the <path>/dev</path>
230 filesystem from the currently running system into the Gentoo/FreeBSD mount
231 point before proceeding with the chroot.
232 </p>
233
234 <pre caption="Mounting the /dev filesystem and chrooting">
235 # <i>mount -t devfs none /mnt/gentoo/dev/</i>
236 # <i>cp /etc/resolv.conf /mnt/gentoo/etc</i>
237 # <i>chroot /mnt/gentoo/ /bin/bash</i>
238 # <i>source /etc/profile</i>
239 </pre>
240
241 <p>
242 After you got hold of the Gentoo/FreeBSD overlay, it's time to link
243 <path>/etc/make.profile</path> to the correct profile and add get your
244 <path>/etc/make.conf</path> ready for Gentoo/FreeBSD.
245 </p>
246
247 <pre caption="Setting up the profile and editing /etc/make.conf">
248 # <i>ln -sf /usr/local/portage/portage-alt-overlay/profiles/default-bsd/fbsd/6.0/x86/ /etc/make.profile</i>
249 <comment>(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)</comment>
250 # <i>ee /etc/make.conf</i>
251 <comment>(Please make sure you add at least the following entries:)</comment>
252 CHOST="i686-gentoo-freebsd6.0"
253 ACCEPT_KEYWORDS="~x86-fbsd ~x86"
254 FEATURES="-sandbox collision-protect"
255 PORTDIR_OVERLAY="/usr/local/portage/portage-alt-overlay"
256 </pre>
257
258 <note>
259 If you're installing using an old 5.4 stage, please replace "5.4" by "6.0" when symlinking the profile and
260 setting the CHOST variable.
261 </note>
262
263 <p>
264 In order to boot correctly, you will need to create the <path>/proc</path>
265 directory.
266 </p>
267
268 <pre caption="Creating the /proc directory">
269 # <i>mkdir /proc</i>
270 </pre>
271
272 <p>
273 Now, you have to obtain a copy of the main Gentoo Portage tree, which depending
274 on your connection might take quite a while.
275 </p>
276
277 <pre caption="Obtaining the Portage tree">
278 # <i>emerge --sync</i>
279 <comment>(It's also possible to retrieve the Portage tree in another way:)</comment>
280 # <i>cd /</i>
281 # <i>wget http://gentoo.osuosl.org/snapshots/portage-latest.tar.bz2</i>
282 # <i>tar -xjf portage-latest.tar.bz2 -C /usr/</i>
283 # <i>emerge --metadata</i>
284 </pre>
285
286 <p>
287 If you want, you can now rebuild the system's core packages.
288 </p>
289
290 <pre caption="Rebuilding the FreeBSD core packages (Optional)">
291 # <i>emerge -e system</i>
292 </pre>
293
294 <p>
295 When you did <c>emerge -e system</c>, the sources for the FreeBSD kernel got
296 installed to <path>/usr/src/sys</path>. If you skipped this step, you can get
297 them in the following way:
298 </p>
299
300 <pre caption="Geting the FreeBSD kernel sources">
301 # <i>emerge freebsd-sources</i>
302 </pre>
303
304 <p>
305 Configuring and compiling a custom kernel is really different from compiling
306 Linux, so if you are not familiar with the process we encourage you to have a
307 look at <uri
308 link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">
309 chapter 8</uri> of the FreeBSD handbook.
310 </p>
311
312 <p>
313 Please note that currently only the "Traditional" way of building the kernel is
314 supported on Gentoo/FreeBSD! Also note that <c>make install</c> will probably
315 ask you for a <path>/boot/device.hints</path> file. A default version can be
316 found in the <path>conf</path> subdirectory of the <c>GENERIC</c> configuration
317 and is called <path>GENERIC.hints</path>.
318 </p>
319
320 <note>
321 When building a kernel, you should use the command "make WERROR=NO_WERROR"
322 because the Gentoo/FreeBSD developers have not yet been able to patch out all
323 occurrences of -Werror and the currently used GCC doesn't accept FreeBSD's
324 extensions to the printf() function.
325 </note>
326
327 <p>
328 Now is the time to do some basic system configuration and settings. First, we
329 are going to setup the filesystem mounting points in <path>/etc/fstab</path>.
330 </p>
331
332 <pre caption="Editing the filesystem in /etc/fstab">
333 # <i>ee /etc/fstab</i>
334 <comment>(This is an example, replace X and Y with the correct numbers for your hard disk.)</comment>
335 #Device Mountpoint Fstype Options Dump Pass
336 /dev/adXsYb none swap sw 0 0
337 /dev/adXsYa / ufs rw 1 1
338 /dev/adXsYe /usr/home ufs rw 2 2
339 /dev/adXsYd /tmp ufs rw 2 2
340 /dev/acdX /cdrom cd9660 ro,noauto 0 0
341 </pre>
342
343 <p>
344 Now would also be a good time to set up your network connection before the final
345 reboot.
346 </p>
347
348 <pre caption="Setting up your network">
349 # <i>ee /etc/conf.d/net</i>
350 <comment>(This is just an example which you have to adjust for your network.)</comment>
351 ifconfig_rl0=("192.168.0.10 netmask 255.255.255.0 broadcast 192.168.0.255")
352 routes_rl0=("-net 0.0.0.0 -host 192.168.0.1")
353 </pre>
354
355 <p>
356 To have your network interface activated at boot time, you have to add it to the default runlevel.
357 </p>
358
359 <pre caption="Adding your network adapter to the default runlevel">
360 # <i>rc-update add net.rl0 default</i>
361 </pre>
362
363 <p>
364 Your system's hostname can be changed in <path>/etc/hostname</path>.
365 </p>
366
367 <pre caption="Setting up the machine's hostname">
368 # <i>echo "YOUR_HOSTNAME_HERE" > /etc/hostname</i>
369 </pre>
370
371 <p>
372 In case you need to use another keyboard layout for your language, you have to
373 set the correct value in <path>/etc/conf.d/syscons</path>. The following example
374 uses the Spanish layout, so you'll have to adjust it to your need if you want to
375 use another one.
376 </p>
377
378 <pre caption="Changing your keyboard layout (Optional)">
379 # <i>ee /etc/conf.d/syscons</i>
380 KEYMAP="spanish.iso.acc"
381 <comment>(Possible layouts can be found in /usr/share/syscons/keymaps).</comment>
382 </pre>
383
384 <impo>
385 Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
386 configuration of your bootloader, otherwise you won't be able to boot your newly
387 installed system! If you don't have another bootloader installed, you should use
388 <c>boot0</c>, as it is currently the only one supported by FreeBSD. In this case
389 please don't forget to use your other operating systems to <c>boot0</c>'s
390 configuration.
391 </impo>
392
393 <pre caption="Installing and setting up boot0">
394 # <i>emerge boot0</i>
395 <comment>(Leave the chroot environment)</comment>
396 # <i>exit</i>
397 <comment>(Issued from outside the chroot)</comment>
398 # <i>fdisk -B -b /mnt/gentoo/boot/boot0 /dev/adX</i>
399 # <i>chroot /mnt/gentoo /bin/bash</i>
400 # <i>disklabel -B adXsY</i>
401 </pre>
402
403 <p>
404 If you need additonal information on setting up <c>boot0</c>, please consult
405 <uri
406 link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot.html">chapter
407 12</uri> of the FreeBSD handbook.
408 </p>
409
410 <p>
411 Now would be a good time to set a password for the <c>root</c> user and to add
412 another user account for your day-to-day work.
413 </p>
414
415 <pre caption="Changing the root password and adding a new user">
416 # <i>passwd</i>
417 <comment>(If you need help in adding a user please consult the FreeBSD handbook).</comment>
418 # <i>adduser</i>
419 </pre>
420
421 <p>
422 Congratulations, you have just finished your Gentoo/FreeBSD installation which
423 you can start exploring after the final reboot. Have fun!
424 </p>
425
426 <pre caption="Rebooting the system">
427 # <i>exit</i>
428 # <i>reboot</i>
429 </pre>
430
431 </body>
432 </section>
433 </chapter>
434
435 <chapter>
436 <title>Developing for Gentoo/FreeBSD</title>
437 <section>
438 <title>How to help</title>
439 <body>
440
441 <p>
442 There are many things you could help with, depending on your skill level and
443 spare time:
444 </p>
445
446 <ul>
447 <li>
448 Working on current ebuilds: this means working closely with ebuild
449 maintainers in order to create patches or modify ebuilds in a way that can
450 be accepted into the main tree.
451 </li>
452 <li>
453 Security: if you are into security, we need you! Although security
454 advisories from the FreeBSD project are tracked and fixed, we can always
455 use help in this area.
456 </li>
457 <li>
458 Contacts: we need people who can get in touch with FreeBSD developers to
459 maintain contacts between us and the original project to exchange patches
460 and discuss various problems and their solutions. Note that this should
461 never involve any kind of spamming of mailing lists or IRC channels.
462 </li>
463 <li>
464 Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
465 will be discovered, which helps us improving the quality of the port. If
466 you are good at describing bugs or problems, we definitely want to hear
467 from you.
468 </li>
469 <li>
470 Other areas where we need help include: system ebuilds, baselayout,
471 creation of installation CDs, documentation, kernel hacking.
472 </li>
473 </ul>
474
475 </body>
476 </section>
477
478 <section>
479 <title>Known issues</title>
480 <body>
481
482 <p>
483 At the moment, there are still quite a lot of known issues. Here are the ones
484 really worth noting:
485 </p>
486
487 <ul>
488 <li>
489 Some init scripts depend on the clock service which we don't provide right
490 now. You can just remove it from the dependencies of the script and report
491 that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
492 remember to use the "Gentoo BSD" product for your submission.
493 </li>
494 <li>glib and gnome in general need a lot of fixes to be backported.</li>
495 <li>
496 The init system currently provided by Gentoo/FreeBSD's baselayout package is
497 not the same version used by Gentoo Linux and lacks some of its features. Work
498 on making newer versions working is underway.
499 </li>
500 </ul>
501
502 </body>
503 </section>
504 </chapter>
505
506 <chapter>
507 <title>Contact</title>
508 <section>
509 <body>
510
511 <p>
512 A list of Gentoo/FreeBSD developers can be found at the <uri
513 link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
514 Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
515 Freenode, as well as the <uri link="/main/en/lists.xml">gentoo-bsd mailing
516 list</uri>.
517 </p>
518
519 </body>
520 </section>
521 </chapter>
522 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20