/[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.13 - (show annotations) (download) (as text)
Tue Jan 10 21:15:20 2006 UTC (8 years, 10 months ago) by vanquirius
Branch: MAIN
Changes since 1.12: +12 -4 lines
File MIME type: application/xml
Add network adapter to runlevel. Fixes bug 118573. Thanks to Michael Kohl <citizen428 at gentoo dot org>.

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

  ViewVC Help
Powered by ViewVC 1.1.20