diff --git a/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml index 936bd263a6..0857fc51d4 100644 --- a/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml @@ -10,8 +10,80 @@ Being a kernel developer requires understanding of the kernel build process. To debug the &os; kernel it is required to be able - to build one. This procedure is documented in the Building and - Installing a Custom Kernel chapter of the &os; - Handbook. + to build one. There are two known ways to do so: + + + + The Traditional Way + + + + The New Way + + + + + It is supposed that the reader of this chapter is familiar + with the information described in the Building and + Installing a Custom Kernel chapter of the &os; + Handbook. If this is not the case, please read through the above + mentioned chapter to understand how the build process + works. + + + + Building a Kernel the <quote>Traditional</quote> Way + + Up to version 4.X of &os; this was the recommended way to + build a new kernel. It can still be used on newer versions + (instead of the buildkernel target of the toplevel + /usr/src/ makefiles). + Building the kernel this way may be useful when working on the + kernel code and it may actually be faster than the + New procedure when only a single option or two were + tweaked in the kernel configuration file. On the other hand, it + might lead to unexpected kernel build breakage when used by + beginners on newer versions of &os;. + + + + Run &man.config.8; to generate the kernel source + code: + + &prompt.root; /usr/sbin/config MYKERNEL + + + + Change into the build directory. &man.config.8; will + print the name of this directory after being run as + above. + + &prompt.root; cd ../compile/MYKERNEL + + + + Compile the kernel: + + &prompt.root; make depend +&prompt.root; make + + + + Install the new kernel: + + &prompt.root; make install + + + + + + Building a Kernel the <quote>New</quote> Way + + This procedure is well supported and recommended under the + latest &os; releases and is documented in the Building and + Installing a Custom Kernel chapter of the &os; + Handbook. + diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml index 3dac25f241..01cb12ae08 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -142,12 +142,161 @@ key issue in the decisions. - Because it makes it harder to import future versions - minor, trivial and/or + Because of some unfortunate design limitations with the RCS file + format and the use of vendor branches, minor, trivial and/or cosmetic changes are strongly discouraged on - files that are still tracking the vendor branch. + files that are still tracking the vendor branch. Spelling + fixes are explicitly included here under the + cosmetic category and are to be avoided. + The repository bloat impact from a single character + change can be rather dramatic. + + Vendor Imports with CVS + + The file utility, used to identify + the format of a file, will be used as example of how this model + works: + + src/contrib/file contains the source as + distributed by the maintainers of this package. Parts that are entirely + not applicable for &os; can be removed. In the case of &man.file.1;, the + python subdirectory and files with the lt + prefix were eliminated before the import, amongst others. + + src/lib/libmagic contains a bmake style + Makefile that uses the standard + bsd.lib.mk makefile rules to produce the library + and install the documentation. + + src/usr.bin/file contains a bmake style + Makefile which will produce and install the + file program and its associated man-pages using the + standard bsd.prog.mk rules. + + The important thing here is that the + src/contrib/file directory is created according to + the rules: it is supposed to contain the sources as distributed (on a + proper vendor-branch and without RCS keyword expansion) with as few + FreeBSD-specific changes as possible. If there are any doubts on + how to go about it, it is imperative that you ask first and not blunder + ahead and hope it works out. + + Because of the previously mentioned design limitations with + vendor branches, it is required that official patches from + the vendor be applied to the original distributed sources and the result + re-imported onto the vendor branch again. Official patches should never + be patched into the FreeBSD checked out version and committed, as this + destroys the vendor branch coherency and makes importing future versions + rather difficult as there will be conflicts. + + Since many packages contain files that are meant for compatibility + with other architectures and environments than FreeBSD, it is + permissible to remove parts of the distribution tree that are of no + interest to FreeBSD in order to save space. Files containing copyright + notices and release-note kind of information applicable to the remaining + files shall not be removed. + + If it seems easier, the bmake + Makefiles can be produced from the dist tree + automatically by some utility, something which would hopefully make it + even easier to upgrade to a new version. If this is done, be sure to + check in such utilities (as necessary) in the + src/tools directory along with the port itself so + that it is available to future maintainers. + + In the src/contrib/file level directory, a file + called FREEBSD-upgrade should be added and it + should state things like: + + + + Which files have been left out. + + + + Where the original distribution was obtained from and/or the + official master site. + + + + Where to send patches back to the original authors. + + + + Perhaps an overview of the FreeBSD-specific changes that have + been made. + + + + Example wording from + src/contrib/groff/FREEBSD-upgrade is + below: + + $FreeBSD: src/contrib/groff/FREEBSD-upgrade,v 1.5.12.1 2005/11/15 22:06:18 ru Exp $ + +This directory contains virgin copies of the original distribution files +on a "vendor" branch. Do not, under any circumstances, attempt to upgrade +the files in this directory via patches and a cvs commit. + +To upgrade to a newer version of groff, when it is available: + 1. Unpack the new version into an empty directory. + [Do not make ANY changes to the files.] + + 2. Use the command: + cvs import -m 'Virgin import of FSF groff v<version>' \ + src/contrib/groff FSF v<version> + + For example, to do the import of version 1.19.2, I typed: + cvs import -m 'Virgin import of FSF groff v1.19.2' \ + src/contrib/groff FSF v1_19_2 + + 3. Follow the instructions printed out in step 2 to resolve any + conflicts between local FreeBSD changes and the newer version. + +Do not, under any circumstances, deviate from this procedure. + +To make local changes to groff, simply patch and commit to the main +branch (aka HEAD). Never make local changes on the FSF branch. + +All local changes should be submitted to Werner Lemberg <wl@gnu.org> or +Ted Harding <ted.harding@nessie.mcc.ac.uk> for inclusion in the next +vendor release. + +ru@FreeBSD.org - 20 October 2005 + + Another approach my also be taken for the list of files to be + excluded, which is especially useful when the list is large or + complicated or where imports happen frequently. By creating a + file FREEBSD-Xlist in the same directory the + vendor source is imported into, containing a list of filename + patterns to be excluded one per line, future imports can often + performed with: + + &prompt.user; tar FREEBSD-Xlist vendor-source.tgz + + An example of a FREEBSD-Xlist file, from + src/contrib/tcsh, is here: + + */BUGS +*/config/a* +*/config/bs2000 +*/config/bsd +*/config/bsdreno +*/config/[c-z]* +*/tests +*/win32 + + + Please do not import FREEBSD-upgrade or + FREEBSD-Xlist with the contributed source. + Rather you should add these files after the initial + import. + + + + diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml index 108e90fd75..d1df3354ae 100644 --- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml @@ -349,11 +349,9 @@ Compiling with <command>cc</command> - This section deals with the gcc - and clang compilers for C and C++, - since they come with the &os; base system. Starting with - &os; 10.X clang is installed as - cc. The + This section deals only with the GNU compiler for C and C++, + since that comes with the base FreeBSD system. It can be + invoked by either cc or gcc. The details of producing a program with an interpreter vary considerably between interpreters, and are usually well covered in the documentation and on-line help for the @@ -379,7 +377,14 @@ Convert the source code into assembly language—this is very close to machine code, but still - understandable by humans. Allegedly. + understandable by humans. Allegedly. + + + To be strictly accurate, cc converts the + source code into its own, machine-independent + p-code instead of assembly language at + this stage. + @@ -532,7 +537,13 @@ an executable that runs faster than normal. You can add a number after the to specify a higher level of optimization, but this often exposes bugs in the - compiler's optimizer. + compiler's optimizer. For instance, the version of + cc that comes with the 2.1.0 release of + FreeBSD is known to produce bad code with the + option in some circumstances. + + Optimization is usually only turned on when compiling + a release version. &prompt.user; cc -O -o foobar foobar.c