diff options
Diffstat (limited to 'en_US.ISO8859-1/articles')
| -rw-r--r-- | en_US.ISO8859-1/articles/contributing/article.sgml | 4915 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/fonts/Makefile | 6 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/fonts/article.sgml | 766 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/formatting-media/Makefile | 7 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/formatting-media/article.sgml | 464 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/mh/Makefile | 7 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/mh/article.sgml | 704 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/multi-os/Makefile | 7 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/multi-os/article.sgml | 682 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/new-users/Makefile | 7 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/new-users/article.sgml | 943 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/programming-tools/Makefile | 7 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/programming-tools/article.sgml | 1835 |
13 files changed, 0 insertions, 10350 deletions
diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml deleted file mode 100644 index 9ddcdbe723..0000000000 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ /dev/null @@ -1,4915 +0,0 @@ - - <chapter id="contrib"> - <title>Contributing to FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>So you want to contribute something to FreeBSD? That is great! We - can always use the help, and FreeBSD is one of those systems that - <emphasis>relies</emphasis> on the contributions of its user base in - order to survive. Your contributions are not only appreciated, they - are vital to FreeBSD's continued growth!</para> - - <para>Contrary to what some people might also have you believe, you do - not need to be a hot-shot programmer or a close personal friend of the - FreeBSD core team in order to have your contributions accepted. The - FreeBSD Project's development is done by a large and growing number of - international contributors whose ages and areas of technical expertise - vary greatly, and there is always more work to be done than there are - people available to do it.</para> - - <para>Since the FreeBSD project is responsible for an entire operating - system environment (and its installation) rather than just a kernel or - a few scattered utilities, our <filename>TODO</filename> list also spans a very wide - range of tasks, from documentation, beta testing and presentation to - highly specialized types of kernel development. No matter what your - skill level, there is almost certainly something you can do to help - the project!</para> - - <para>Commercial entities engaged in FreeBSD-related enterprises are - also encouraged to contact us. Need a special extension to make your - product work? You will find us receptive to your requests, given that - they are not too outlandish. Working on a value-added product? - Please let us know! We may be able to work cooperatively on some - aspect of it. The free software world is challenging a lot of - existing assumptions about how software is developed, sold, and - maintained throughout its life cycle, and we urge you to at least give - it a second look.</para> - - - <sect1> - <title>What Is Needed</title> - - <para>The following list of tasks and sub-projects represents - something of an amalgam of the various core team <filename>TODO</filename> lists and user - requests we have collected over the last couple of months. Where - possible, tasks have been ranked by degree of urgency. If you are - interested in working on one of the tasks you see here, send mail to - the coordinator listed by clicking on their names. If no - coordinator has been appointed, maybe you would like to - volunteer?</para> - - - <sect2> - <title>High priority tasks</title> - - <para>The following tasks are considered to be urgent, usually - because they represent something that is badly broken or sorely - needed:</para> - - <orderedlist> - - <listitem> - <para>3-stage boot issues. Overall coordination: - &a.hackers;</para> - - - <itemizedlist> - - <listitem> - <para>Autodetect memory over 64MB properly.</para> - </listitem> - - <listitem> - <para>Move userconfig (-c) into 3rd stage boot.</para> - </listitem> - - <listitem> - <para>Do WinNT compatible drive tagging so that the 3rd - stage can provide an accurate mapping of BIOS - geometries for disks.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>Filesystem problems. Overall coordination: &a.fs;</para> - <itemizedlist> - - <listitem> - <para>Fix the MSDOS file system.</para> - </listitem> - - <listitem> - <para>Clean up and document the nullfs filesystem code. - Coordinator: &a.gibbs;</para> - </listitem> - - <listitem> - <para>Fix the union file system. Coordinator: - &a.dyson;</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>Implement kernel and user vm86 support. Coordinator: - &a.hackers;</para> - </listitem> - - <listitem> - <para>Implement Int13 vm86 disk driver. Coordinator: - &a.hackers;</para> - </listitem> - - <listitem> - <para>SCSI driver issues. Overall coordination: - &a.hackers;</para> - - - <itemizedlist> - - <listitem> - <para>Support tagged queuing generically. Requires a - rewrite of how we do our command queuing, but we need - this anyway to for prioritized I/O (CD-R - writers/scanners).</para> - </listitem> - - <listitem> - <para>Better error handling (Busy status and - retries).</para> - </listitem> - - <listitem> - <para>Merged Scatter-Gather list creation code.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>Kernel issues. Overall coordination: &a.hackers;</para> - - - <itemizedlist> - - <listitem> - <para>Complete the eisaconf conversion of all existing - drivers.</para> - </listitem> - - <listitem> - <para>Change all interrupt routines to take a (void *) - instead of using unit numbers.</para> - </listitem> - - <listitem> - <para>Merge EISA/PCI/ISA interrupt registration - code.</para> - </listitem> - - <listitem> - <para>Split PCI/EISA/ISA probes out from drivers like - bt742a.c (WIP)</para> - </listitem> - - <listitem> - <para>Fix the syscons ALT-Fn/vt switching hangs. - Coordinator: &a.sos;</para> - </listitem> - - <listitem> - <para>Rewrite the Intel Etherexpress 16 driver.</para> - </listitem> - - <listitem> - <para>Merge the 3c509 and 3c590 drivers (essentially - provide a PCI probe for ep.c).</para> - </listitem> - - <listitem> - <para>Support Adaptec 3985 (first as a simple 3 channel - SCSI card) Coordinator: &a.gibbs;</para> - </listitem> - - <listitem> - <para>Support Advansys SCSI controller products. - Coordinator: &a.gibbs;</para> - </listitem> - - </itemizedlist> - - </listitem> - - </orderedlist> - - </sect2> - - <sect2> - <title>Medium priority tasks</title> - - <para>The following tasks need to be done, but not with any - particular urgency:</para> - - <orderedlist> - - <listitem> - <para>Port AFS (Andrew File System) to FreeBSD Coordinator: - Alexander Seth Jones <email>ajones@ctron.com</email></para> - </listitem> - - <listitem> - <para>MCA support? This should be finalized one way or the - other.</para> - </listitem> - - <listitem> - <para>Full LKM based driver support/Configuration Manager.</para> - - - <itemizedlist> - - <listitem> - <para>Devise a way to do all LKM registration without - ld. This means some kind of symbol table in the - kernel.</para> - </listitem> - - <listitem> - <para>Write a configuration manager (in the 3rd stage - boot?) that probes your hardware in a sane manner, - keeps only the LKMs required for your hardware, - etc.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>PCMCIA/PCCARD. Coordinators: &a.nate; and &a.phk;</para> - <itemizedlist> - - <listitem> - <para>Documentation!</para> - </listitem> - - <listitem> - <para>Reliable operation of the pcic driver (needs - testing).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for - <filename>sio.c</filename> (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for - <filename>ed.c</filename> (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for - <filename>ep.c</filename> (mostly done).</para> - </listitem> - - <listitem> - <para>User-mode recognizer and handler (partially - done).</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>Advanced Power Management. Coordinators: &a.nate; and - &a.phk;</para> - <itemizedlist> - - <listitem> - <para>APM sub-driver (mostly done).</para> - </listitem> - - <listitem> - <para>IDE/ATA disk sub-driver (partially done).</para> - </listitem> - - <listitem> - <para>syscons/pcvt sub-driver.</para> - </listitem> - - <listitem> - <para>Integration with the PCMCIA/PCCARD drivers - (suspend/resume).</para> - </listitem> - - </itemizedlist> - - </listitem> - - </orderedlist> - - </sect2> - - <sect2> - <title>Low priority tasks</title> - - <para>The following tasks are purely cosmetic or represent such an - investment of work that it is not likely that anyone will get them - done anytime soon:</para> - - <para>The first 20 items are from Terry Lambert - <email>terry@lambert.org</email></para> - - <orderedlist> - - <listitem> - <para>Ability to make BIOS calls from protected mode using V86 - mode on the processor and return the results via a mapped - interrupt IPC mechanism to the protected mode caller.</para> - </listitem> - - <listitem> - <para>Drivers built into the kernel that use the BIOS call - mechanism to allow them to be independent of the actual - underlying hardware the same way that DOS is independent of - the underlying hardware. This includes NetWork and ASPI - drivers loaded in DOS prior to BSD being loaded by a - DOS-based loader program, which means potential polling, - which means DOS-not-busy interrupt generation for V86 - machines by the protected mode kernel.</para> - </listitem> - - <listitem> - <para>An image format that allows tagging of such drivers data - and text areas in the default kernel executable so that that - portion of the kernel address space may be recovered at a - later time, after hardware specific protected mode drivers - have been loaded and activated. This includes separation of - BIOS based drivers from each other, since it is better to - run with a BIOS based driver in all cases than to not run at - all.</para> - </listitem> - - <listitem> - <para>Abstraction of the bus interface mechanism. Currently, - PCMCIA, EISA, and PCI busses are assumed to be bridged from - ISA. This is not something which should be assumed.</para> - </listitem> - - <listitem> - <para>A configuration manager that knows about PNP events, - including power management events, insertion, extraction, - and bus (PNP ISA and PCMCIA bridging chips) vs. card level - event management.</para> - </listitem> - - <listitem> - <para>A topological sort mechanism for assigning reassignable - addresses that do not collide with other reassignable and - non-reassignable device space resource usage by fixed - devices.</para> - </listitem> - - <listitem> - <para>A registration based mechanism for hardware services - registration. Specifically, a device centric registration - mechanism for timer and sound and other system critical - service providers. Consider Timer2 and Timer0 and speaker - services as one example of a single monolithic service - provider.</para> - </listitem> - - <listitem> - <para>A kernel exported symbol space in the kernel data space - accessible by an LKM loader mechanism that does relocation - and symbol space manipulation. The intent of this interface - is to support the ability to demand load and unload kernel - modules.</para> - </listitem> - - <listitem> - <para>NetWare Server (protected mode ODI driver) loader and - subservices to allow the use of ODI card drivers supplied - with network cards. The same thing for NDIS drivers and - NetWare SCSI drivers.</para> - </listitem> - - <listitem> - <para>An "upgrade system" option that works on Linux boxes - instead of just previous rev FreeBSD boxes.</para> - </listitem> - - <listitem> - <para>Splitting of the console driver into abstraction layers, - both to make it easier to port and to kill the X and - ThinkPad and PS/2 mouse and LED and console switching and - bouncing NumLock problems once and for all.</para> - </listitem> - - <listitem> - <para>Other kernel emulation environments for other foreign - drivers as opportunity permits. SCO and Solaris are good - candidates, followed by UnixWare, etc.</para> - </listitem> - - <listitem> - <para>Processor emulation environments for execution of - foreign binaries. This is easier than it sounds if the - system call interface does not change much.</para> - </listitem> - - <listitem> - <para>Streams to allow the use of commercial streams drivers.</para> - </listitem> - - <listitem> - <para>Kernel multithreading (requires kernel preemption).</para> - </listitem> - - <listitem> - <para>Symmetric Multiprocessing with kernel preemption - (requires kernel preemption).</para> - </listitem> - - <listitem> - <para>A concerted effort at support for portable computers. - This is somewhat handled by changing PCMCIA bridging rules - and power management event handling. But there are things - like detecting internal vs. external display and picking a - different screen resolution based on that fact, not spinning - down the disk if the machine is in dock, and allowing - dock-based cards to disappear without affecting the machines - ability to boot (same issue for PCMCIA).</para> - </listitem> - - <listitem> - <para>Reorganization of the source tree for multiple platform - ports.</para> - </listitem> - - <listitem> - <para>A <command>make world</command> that "makes the world" (rename the - current one to <command>make regress</command> if that is all it is good - for).</para> - </listitem> - - <listitem> - <para>A 4M (preferably smaller!) memory footprint.</para> - </listitem> - - </orderedlist> - - </sect2> - - <sect2> - <title>Smaller tasks</title> - - <para>Most of the tasks listed in the previous sections require - either a considerable investment of time or an in-depth knowledge - of the FreeBSD kernel (or both). However, there are also many - useful tasks which are suitable for "weekend hackers", - or people without programming skills.</para> - - - <orderedlist> - - <listitem> - <para>If you run FreeBSD-current and have a good Internet - connection, there is a machine <hostid role="fqdn">current.freebsd.org</hostid> which - builds a full release once a day — every now and again, try - and install the latest release from it and report any - failures in the process.</para> - </listitem> - - <listitem> - <para>Read the <email>freebsd-bugs</email> mailing list. There might be a - problem you can comment constructively on or with patches - you can test. Or you could even try to fix one of the - problems yourself.</para> - </listitem> - - <listitem> - <para>Read through the FAQ and Handbook periodically. If - anything is badly explained, out of date or even just - completely wrong, let us know. Even better, send us a fix - (SGML is not difficult to learn, but there is no objection - to ASCII submissions).</para> - </listitem> - - <listitem> - <para>Help translate FreeBSD documentation into your native - language (if not already available) — just send an email to - &a.doc; asking if anyone is working on it. Note that you - are not committing yourself to translating every single - FreeBSD document by doing this — in fact, the documentation - most in need of translation is the installation - instructions.</para> - </listitem> - - <listitem> - <para>Read the freebsd-questions mailing list and the - newsgroup <literal>comp.unix.bsd.freebsd.misc</literal> occasionally (or even - regularly). It can be very satisfying to share your - expertise and help people solve their problems; sometimes - you may even learn something new yourself! These forums can - also be a source of ideas for things to work on.</para> - </listitem> - - <listitem> - <para>If you know of any bugfixes which have been successfully - applied to -current but have not been merged into -stable - after a decent interval (normally a couple of weeks), send - the committer a polite reminder.</para> - </listitem> - - <listitem> - <para>Move contributed software to - <filename>src/contrib</filename> in the source tree.</para> - </listitem> - - <listitem> - <para>Make sure code in <filename>src/contrib</filename> is up - to date.</para> - </listitem> - - <listitem> - <para>Look for year 2000 bugs (and fix any you find!)</para> - </listitem> - - <listitem> - <para>Build the source tree (or just part of it) with extra - warnings enabled and clean up the warnings.</para> - </listitem> - - <listitem> - <para>Fix warnings for ports which do deprecated things like - using gets() or including malloc.h.</para> - </listitem> - - <listitem> - <para>If you have contributed any ports, send your patches - back to the original author (this will make your life easier - when they bring out the next version)</para> - </listitem> - - <listitem> - <para>Suggest further tasks for this list!</para> - </listitem> - - </orderedlist> - - - </sect2> - </sect1> - - <sect1> - <title>How to Contribute</title> - - <para>Contributions to the system generally fall into one or more of - the following 6 categories:</para> - - - <sect2 id="contrib-general"> - <title>Bug reports and general commentary</title> - - <para>An idea or suggestion of <emphasis>general</emphasis> - technical interest should be mailed to the &a.hackers;. Likewise, - people with an interest in such things (and a tolerance for a - <emphasis>high</emphasis> volume of mail!) may subscribe to the - hackers mailing list by sending mail to &a.majordomo;. See - <xref linkend="eresources-mail" remap="mailing lists"> for more - information about this and other mailing lists.</para> - - <para>If you find a bug or are submitting a specific change, please - report it using the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>program or its - <ulink URL="http://www.freebsd.org/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug report. - Unless they exceed 65KB, include any patches directly in the - report. Consider compressing them and using - <citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> if they exceed 20KB.</para> - - <para>After filing a report, you should receive confirmation along - with a tracking number. Keep this tracking number so that you can - update us with details about the problem by sending mail to <email>bug-followup@FreeBSD.ORG</email>. Use the number as the message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional information for any bug report should be submitted this way.</para> - - <para>If you do not receive confirmation in a timely fashion (3 days - to a week, depending on your email connection) or are, for some - reason, unable to use the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, - then you may ask someone to file it for you by sending mail to the - &a.bugs;.</para> - - </sect2> - - <sect2> - <title>Changes to the documentation</title> - - <para>Changes to the documentation are overseen by the &a.doc;. Send - submissions and changes (even small ones are welcome!) using - <command>send-pr</command> as described in - <xref linkend="contrib-general" remap="Bug Reports and General - Commentary">.</para> - - </sect2> - - <sect2> - <title>Changes to existing source code</title> - - <para>An addition or change to the existing source code is a - somewhat trickier affair and depends a lot on how far out of date - you are with the current state of the core FreeBSD development. - There is a special on-going release of FreeBSD known as - “FreeBSD-current” which is made available in a variety of ways - for the convenience of developers working actively on the system. - See <xref linkend="current" - remap="Staying current with FreeBSD"> for more information - about getting and using FreeBSD-current.</para> - - <para>Working from older sources unfortunately means that your - changes may sometimes be too obsolete or too divergent for easy - re-integration into FreeBSD. Chances of this can be minimized - somewhat by subscribing to the &a.announce; and the &a.current; - lists, where discussions on the current state of the system take - place.</para> - - <para>Assuming that you can manage to secure fairly up-to-date - sources to base your changes on, the next step is to produce a set - of diffs to send to the FreeBSD maintainers. This is done with - the <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, with the “context diff” - form being preferred. For example:</para> - - <para><informalexample> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - </informalexample> - - or - - <informalexample> - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - </informalexample> - - would generate such a set of context diffs for - the given source file or directory hierarchy. See the man page - for <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more details.</para> - - <para>Once you have a set of diffs (which you may test with the - <citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry> command), you should submit them for - inclusion with FreeBSD. Use the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> - program as described in - <xref linkend="contrib-general" remap="Bug Reports and General - Commentary">. <emphasis>Do not</emphasis> just send the diffs to - the &a.hackers; or they will get lost! We greatly appreciate your - submission (this is a volunteer project!); because we are busy, we - may not be able to address it immediately, but it will remain in - the pr database until we do.</para> - - <para>If you feel it appropriate (e.g. you have added, deleted, or - renamed files), bundle your changes into a <command>tar</command> file and run the - <citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> program on it. Shar archives are - also welcome.</para> - - <para>If your change is of a potentially sensitive nature, e.g. you - are unsure of copyright issues governing its further distribution - or you are simply not ready to release it without a tighter review - first, then you should send it to &a.core; directly rather than - submitting it with <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The core - mailing list reaches a much smaller group of people who do much of - the day-to-day work on FreeBSD. Note that this group is also - <emphasis>very busy</emphasis> and so you should only send mail to - them where it is truly necessary.</para> - - <para>Please refer to <command>man 9 intro</command> and - <command>man 9 style</command> for some information on - coding style. We would appreciate it if you were at least aware - of this information before submitting code.</para> - - </sect2> - - <sect2> - <title>New code or major value-added packages</title> - - <para>In the rare case of a significant contribution of a large body - work, or the addition of an important new feature to FreeBSD, it - becomes almost always necessary to either send changes as - uuencode'd tar files or upload them to our ftp site <ulink - URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming</ulink>.</para> - - <para>When working with large amounts of code, the touchy subject of - copyrights also invariably comes up. Acceptable copyrights for - code included in FreeBSD are:</para> - - - <orderedlist> - - <listitem> - <para>The BSD copyright. This copyright is most preferred due - to its “no strings attached” nature and general - attractiveness to commercial enterprises. Far from - discouraging such commercial use, the FreeBSD Project - actively encourages such participation by commercial - interests who might eventually be inclined to invest - something of their own into FreeBSD.</para> - </listitem> - - <listitem> - <para>The GNU Public License, or “GPL”. This license is not - quite as popular with us due to the amount of extra effort - demanded of anyone using the code for commercial purposes, - but given the sheer quantity of GPL'd code we currently - require (compiler, assembler, text formatter, etc) it would - be silly to refuse additional contributions under this - license. Code under the GPL also goes into a different part - of the tree, that being <filename>/sys/gnu</filename> or - <filename>/usr/src/gnu</filename>, and is therefore easily - identifiable to anyone for whom the GPL presents a - problem.</para> - </listitem> - - </orderedlist> - - - <para>Contributions coming under any other type of copyright must be - carefully reviewed before their inclusion into FreeBSD will be - considered. Contributions for which particularly restrictive - commercial copyrights apply are generally rejected, though the - authors are always encouraged to make such changes available - through their own channels.</para> - - <para>To place a “BSD-style” copyright on your work, include the - following text at the very beginning of every source code file you - wish to protect, replacing the text between the - <literal>%%</literal> with the appropriate information.</para> - - <programlisting> -Copyright (c) %%proper_years_here%% - %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - $Id$</programlisting> - - <para>For your convenience, a copy of this text can - be found in - <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> - - </sect2> - - <sect2 id="porting"> - <title>Porting an existing piece of free software</title> - - <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and - &a.obrien;.<!-- <br> -->28 August 1996.</emphasis></para> - - <para>The porting of freely available software, while perhaps not as - gratifying as developing your own from scratch, is still a vital - part of FreeBSD's growth and of great usefulness to those who - would not otherwise know where to turn for it. All ported - software is organized into a carefully organized hierarchy known - as “the ports collection”. The collection enables a new user to - get a quick and complete overview of what is available for FreeBSD - in an easy-to-compile form. It also saves considerable space by - not actually containing the majority of the sources being ported, - but merely those differences required for running under FreeBSD.</para> - - <para>What follows are some guidelines for creating a new port for - FreeBSD 3.x. The bulk of the work is done by - <filename>/usr/share/mk/bsd.port.mk</filename>, which all port - Makefiles include. Please refer to that file for more details on - the inner workings of the ports collection. Even if you don't - hack Makefiles daily, it is well commented, and you will still - gain much knowledge from it.</para> - - - <sect3 id="porting-starting"> - <title>Before Starting the Port</title> - - <note> - <para>Only a fraction of the overridable variables - are mentioned in - this document. Most (if not all) are documented at the start - of <filename>bsd.port.mk</filename>. This file uses a - non-standard tab setting. <command>Emacs</command> and - <command>Vim</command> should recognize the setting on loading - the file. <command>vi</command> or <command>ex</command> can - be set to using the correct value by typing <literal>:set - tabstop=4</literal> once the file has been loaded.</para> - </note> - - <para>You may come across code that needs modifications or - conditional compilation based upon what version of UNIX it is - running under. If you need to make such changes to the code for - conditional compilation, make sure you make the changes as - general as possible so that we can back-port code to FreeBSD 1.x - systems and cross-port to other BSD systems such as 4.4BSD from - CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para> - - <para>The preferred way to tell 4.3BSD/Reno (1990) and newer - versions of the BSD code apart is by using the - <acronym>BSD</acronym> macro defined in - <filename><sys/param.h></filename>. Hopefully that file - is already included; if not, add the code:</para> - - <programlisting> -#ifdef (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif</programlisting> - - <para>to the proper place in the <filename>.c</filename> file. We - believe that every system that defines these to symbols has - <filename>sys/param.h</filename>. If you find a system that - doesn't, we would like to know. Please send mail to - &a.ports;.</para> - - <para>Another way is to use the GNU Autoconf style of doing - this:</para> - - <programlisting> -#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif</programlisting> - - <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to - the <makevar>CFLAGS</makevar> in the Makefile for this - method.</para> - - <para>Once you have <filename>sys/param.h</filename> - included, you may use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199103))</programlisting> - - <para>to detect if the code is being compiled on a 4.3 Net2 code - base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, - BSD/386 1.1 and below).</para> - - <para>Use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199306))</programlisting> - - <para>to detect if the code is being compiled on a 4.4 code base - or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or - above).</para> - - <para>The value of the BSD macro is 199506 for the 4.4BSD-Lite2 - code base. This is stated for informational purposes only. It - should not be used to distinguish between version of FreeBSD - based only on 4.4-Lite vs. versions that have merged in changes - from 4.4-Lite2. The __FreeBSD__ macro should be used - instead.</para> - - <para>Use sparingly:</para> - - - <itemizedlist> - - <listitem> - <para><literal>__FreeBSD__</literal> is defined in all - versions of FreeBSD. Use it if the change you are making - ONLY affects FreeBSD. Porting gotchas like the use of - <literal>sys_errlist[]</literal> vs - <function>strerror()</function> are Berkeleyisms, not - FreeBSD changes.</para> - </listitem> - - <listitem> - <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is - defined to be <literal>2</literal>. In earlier - versions, it is <literal>1</literal>. Later - versions will bump it to match their major version number.</para> - </listitem> - - <listitem> - <para>If you need to tell the difference between a FreeBSD - 1.x system and a FreeBSD 2.x or 3.x system, usually the - right answer is to use the <acronym>BSD</acronym> macros - described above. If there actually is a FreeBSD specific - change (such as special shared library options when using - <command>ld</command>) then it is OK to use - <literal>__FreeBSD__</literal> and <literal>#if - __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x - and later system. If you need more granularity in - detecting FreeBSD systems since 2.0-RELEASE you can use - the following:</para> - - <programlisting> -#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif</programlisting> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Release</entry> - <entry><literal>_FreeBSD_version</literal></entry> - </row> - </thead> - - <tbody> - <row> - <entry>2.0-RELEASE</entry> - <entry>119411</entry> - </row> - - <row> - <entry>2.1-currents</entry> - <entry>199501, 199503</entry> - </row> - - <row> - <entry>2.0.5-RELEASE</entry> - <entry>199504</entry> - </row> - - <row> - <entry>2.2-current before 2.1</entry> - <entry>199508</entry> - </row> - - <row> - <entry>2.1.0-RELEASE</entry> - <entry>199511</entry> - </row> - - <row> - <entry>2.2-current before 2.1.5</entry> - <entry>199512</entry> - </row> - - <row> - <entry>2.1.5-RELEASE</entry> - <entry>199607</entry> - </row> - - <row> - <entry>2.2-current before 2.1.6</entry> - <entry>199608</entry> - </row> - - <row> - <entry>2.1.6-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.1.7-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.2-RELEASE</entry> - <entry>220000</entry> - </row> - - <row> - <entry>2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after texinfo-3.9</entry> - <entry>221001</entry> - </row> - - <row> - <entry>2.2-STABLE after top</entry> - <entry>221002</entry> - </row> - - <row> - <entry>2.2.2-RELEASE</entry> - <entry>222000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.2-RELEASE</entry> - <entry>222001</entry> - </row> - - <row> - <entry>2.2.5-RELEASE</entry> - <entry>225000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.5-RELEASE</entry> - <entry>225001</entry> - </row> - - <row> - <entry>2.2-STABLE after ldconfig -R merge</entry> - <entry>225002</entry> - </row> - - <row> - <entry>2.2.6-RELEASE</entry> - <entry>226000</entry> - </row> - - <row> - <entry>2.2.7-RELEASE</entry> - <entry>227000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.7-RELEASE</entry> - <entry>227001</entry> - </row> - - <row> - <entry>3.0-current before mount(2) change</entry> - <entry>300000</entry> - </row> - - <row> - <entry>3.0-current as of November 1996</entry> - <entry>300001</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </itemizedlist> - - <note> - <para>Note that 2.2-STABLE sometimes identifies itself as - “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to - be year followed by the month, but we decided to change it - to a more straightforward major/minor system starting from - 2.2. This is because the parallel development on several - branches made it infeasible to classify the releases simply - by their real release dates. If you are making a port now, - you don't have to worry about old -current's; they are - listed here just for your reference.</para> - </note> - - - <para>In the hundreds of ports that have been done, there have - only been one or two cases where <literal>__FreeBSD__</literal> - should have been used. Just because an earlier port screwed up - and used it in the wrong place does not mean you should do so - too.</para> - - </sect3> - - <sect3> - <title>Quick Porting</title> - - <para>This section tells you how to do a quick port. In many - cases, it is not enough, but we will see.</para> - - <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to - <filename>/usr/ports/distfiles</filename>.</para> - - <note> - <para>The following assumes that the software compiled - out-of-the-box, i.e., there was absolutely no change required - for the port to work on your FreeBSD box. If you needed to - change something, you will have to refer to the next section - too.</para> - </note> - - <sect4> - <title>Writing the <filename>Makefile</filename></title> - - <para>The minimal <filename>Makefile</filename> would - look something like this:</para> - - <programlisting> -# New ports collection makefile for: oneko -# Version required: 1.1b -# Date created: 5 December 1994 -# Whom: asami -# -# $Id$ -# - -DISTNAME= oneko-1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= asami@FreeBSD.ORG - -MAN1= oneko.1 -MANCOMPRESSED= yes -USE_IMAKE= yes - -.include <bsd.port.mk></programlisting> - - <para>See if you can figure it out. Do not worry about the - contents of the <literal>$Id$</literal> - line, it will be filled in automatically by CVS when the port - is imported to our main ports tree. You can find a more - detailed example in the <xref - linkend="porting-samplem" remap="sample Makefile"> - section.</para> - - </sect4> - - <sect4> - <title>Writing the description files</title> - - <para>There are three required description files that are - required for any port, whether they actually package or not. - They are <filename>COMMENT</filename>, - <filename>DESCR</filename>, and <filename>PLIST</filename>, - and reside in the <filename>pkg</filename> - subdirectory.</para> - - - <sect5> - <title><filename>COMMENT</filename></title> - - <para>This is the one-line description of the port. - <emphasis>Please</emphasis> do not include the package name (or version - number of the software) in the comment. Here is - an example:</para> - - <programlisting> -A cat chasing a mouse all over the screen.</programlisting> - - </sect5> - - <sect5> - <title><filename>DESCR</filename></title> - - <para>This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient.</para> - - <note> - <para>This is <emphasis>not</emphasis> a manual nor an - in-depth description on how to use or compile the port. In - particular, <emphasis>please do not just copy the - <filename>README</filename> file here</emphasis>, unless, - of course, it is a concise description of the port.</para> - </note> - - <para>It is recommended that you sign the name at the end of - this file, as in:</para> - - <programlisting> -This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -- Satoshi -asami@cs.berkeley.edu</programlisting> - - </sect5> - - <sect5> - <title><filename>PLIST</filename></title> - - <para>This file lists all the files installed by the port. It - is also called the `packing list' because the package is - generated by packing the files listed here. The pathnames - are relative to the installation prefix (usually - <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename>). Also it is assumed the - manpages will be compressed.</para> - - <para>Here is a small example:</para> - - <programlisting> -bin/oneko -man/man1/oneko.1.gz -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm</programlisting> - - <para>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page - for details on the packing list.</para> - - </sect5> - </sect4> - - <sect4> - <title>Creating the checksum file</title> - - <para>Just type <command>make makesum</command>. - The ports make rules will automatically generate the file - <filename>files/md5</filename>.</para> - - </sect4> - - <sect4> - <title>Testing the port</title> - - <para>You should make sure that the port rules do exactly what - you want it to do, including packaging up the port. Try doing - <command>make install</command>, <command>make package</command> and then <command>make deinstall</command> and see if all the files - and directories are correctly deleted. Then do a <command>pkg_add `make package-name`.tgz</command> and see - if everything re-appears and works correctly. Then do another - <command>make deinstall</command> and then - <command>make reinstall; make package</command> - to make sure you haven't included in the packing list any - files that are not installed by your port.</para> - - </sect4> - - <sect4 id="porting-submitting"> - <title>Submitting the port</title> - - <para>Now that you are happy with your port, the only thing - remaining is to put it in the main FreeBSD ports tree and make - everybody else happy about it too. To accomplish this, pack - the necessary files (everything described in this section — - in particular do <emphasis>not</emphasis> include the original - source tarball, the <filename>work</filename> - subdirectory or the package) into a - <filename>.tar.gz</filename> file, stick it in the directory - <filename>ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/</filename> and send mail to us using - <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> (please classify it as category - <literal>ports</literal> and class <literal>change-request</literal>). There is no need to - upload the package, we will build it by ourselves. We will - take a look, get back to you if necessary, and put it in the - tree. Your name will also appear in the list of “Additional - FreeBSD contributors” on the FreeBSD Handbook and other files. - Isn't that great?!? <!-- smiley -->:)</para> - - </sect4> - </sect3> - - <sect3> - <title>Slow Porting</title> - - <para>Ok, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will - explain, step by step, how to modify it to get it to work with - the ports paradigm.</para> - - - <sect4> - <title>How things work</title> - - <para>First, this is the sequence of events which occurs when - the user first types <command>make</command> in - your port's directory, and you may find that having - <filename>bsd.port.mk</filename> in another window while you - read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people - do... <!-- smiley --><emphasis>:></emphasis></para> - - - <procedure> - - <step> - <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is - responsible for making sure that the tarball exists - locally in <makevar>DISTDIR</makevar>. - If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the - URL <makevar>MASTER_SITES</makevar>, - which is set in the Makefile, as well as our main ftp - site at <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para> - </step> - - <step> - <para>The <maketarget>extract</maketarget> target is run. It looks for your ports' - distribution file in <makevar>DISTDIR</makevar> (typically a gzip'd - tarball) and unpacks it into a temporary subdirectory - specified by <makevar>WRKDIR</makevar> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <maketarget>patch</maketarget> target is run. First, any patches defined - in <makevar>PATCHFILES</makevar> are - applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the - <filename>patches</filename> subdirectory), they are - applied at this time in alphabetical order.</para> - </step> - - <step> - <para>The <maketarget>configure</maketarget> target is run. This can do any one of - many different things.</para> - - <orderedlist> - - <listitem> - <para>If it exists, - <filename>scripts/configure</filename> is run.</para> - </listitem> - - <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> - is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>USE_IMAKE</makevar> is set, - <makevar>XMKMF</makevar> - (default: <command>xmkmf - -a</command>) is run.</para> - </listitem> - - </orderedlist> - - </step> - - <step> - <para>The <maketarget>build</maketarget> target is run. This is responsible for - descending into the ports' private working directory - (<makevar>WRKSRC</makevar>) and - building it. If <makevar>USE_GMAKE</makevar> is set, GNU - <command>make</command> will be used, - otherwise the system <command>make</command> - will be used.</para> - </step> - - </procedure> - - - <para>The above are the default actions. In addition, you can - define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts - with those names, in the <filename>scripts</filename> - subdirectory, and they will be run before or after the default - actions are done.</para> - - <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your - Makefile, and a file <filename>pre-build</filename> in the - <filename>scripts</filename> subdirectory, the - <maketarget>post-extract</maketarget> target will be - called after the regular extraction actions, and the - <filename>pre-build</filename> script will be executed before - the default build rules are done. It is recommended that you - use <filename>Makefile</filename> targets if the actions are - simple enough, because it will be easier for someone to figure - out what kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the - commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with - the default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> target in - your <filename>Makefile</filename>.</para> - - <note> - <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than - make sure all the stages up to that one is completed and - call the real targets or scripts, and they are not intended - to be changed. If you want to fix the extraction, fix - <maketarget>do-extract</maketarget>, but never ever - touch <maketarget>extract</maketarget>!</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make</command>, let us go through the - recommended steps to create the perfect port.</para> - - </sect4> - - <sect4> - <title>Getting the original sources</title> - - <para>Get the original sources (normally) as a compressed - tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or - <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into - <makevar>DISTDIR</makevar>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>If you cannot find a ftp/http site that is well-connected - to the net, or can only find sites that have irritatingly - non-standard formats, we can “house” it ourselves by putting - it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this - location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to - the &a.ports;if you are not sure what to do.</para> - - <para>If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - <makevar>DISTDIR</makevar>. Do not worry if - they come from site other than where you got the main source - tarball, we have a way to handle these situations (see the - description of <xref linkend="porting-patchfiles" - remap="PATCHFILES"> below).</para> - - </sect4> - - <sect4> - <title>Modifying the port</title> - - <para>Unpack a copy of the tarball in a private directory and - make whatever changes are necessary to get the port to compile - properly under the current version of FreeBSD. Keep - <emphasis>careful track</emphasis> of everything you do, as - you will be automating the process shortly. Everything, - including the deletion, addition or modification of files - should be doable using an automated script or patch file when - your port is finished.</para> - - <para>If your port requires significant user - interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic <application>Configure</application> scripts - and perhaps do something similar yourself. The goal of the - new ports collection is to make each port as “plug-and-play” - as possible for the end-user while using a minimum of disk - space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and - other files you have created and contributed to the FreeBSD - ports collection are assumed to be covered by the standard - BSD copyright conditions.</para> - </note> - </sect4> - - <sect4> - <title>Patching</title> - - <para>In the preparation of the port, files that have been added - or changed can be picked up with a recursive diff for later - feeding to patch. Each set of patches you wish to apply - should be collected into a file named - <filename>patch-<replaceable>xx</replaceable></filename> where - <replaceable>xx</replaceable> denotes the sequence in which - the patches will be applied — these are done in - <emphasis>alphabetical order</emphasis>, thus - <literal>aa</literal> first, <literal>ab</literal> second and so on. These files - should be stored in <makevar>PATCHDIR</makevar>, from where they will be - automatically applied. All patches should be relative to - <makevar>WRKSRC</makevar> (generally the - directory your port's tarball unpacks itself into, that being - where the build is done). To make fixes and upgrades easier - you should avoid having more than one patch fix the same file - (e.g., patch-aa and patch-ab both changing <makevar>WRKSRC</makevar>/foobar.c).</para> - - </sect4> - - <sect4> - <title>Configuring</title> - - <para>Include any additional customization commands to your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned - above, you can also do this as <filename>Makefile</filename> - targets and/or scripts with the name - <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - - </sect4> - - <sect4> - <title>Handling user input</title> - - <para>If your port requires user input to build, configure or - install, then set <makevar>IS_INTERACTIVE</makevar> in your - Makefile. This will allow “overnight builds” to skip your port - if the user sets the variable <envar>BATCH</envar> in his - environment (and if the user sets the variable - <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis> - those ports requiring interaction are built).</para> - - </sect4> - </sect3> - - <sect3> - <title>Configuring the Makefile</title> - - <para>Configuring the Makefile is pretty simple, and again we - suggest that you look at existing examples before starting. - Also, there is a <xref linkend="porting-samplem" remap="sample - Makefile"> in this handbook, so take a look and please follow - the ordering of variables and sections in that template to make - your port easier for others to read.</para> - - <para>Now, consider the following problems in sequence as you - design your new Makefile:</para> - - - <sect4> - <title>The original source</title> - - <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd - tarball? If so, you can go on to the next step. If not, you - should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on - how alien a format your port's distribution file is. (The - most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>, - when the tarball is condensed by regular compress, not - gzip.)</para> - - <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override - the default, though this should be rarely, if ever, - necessary.</para> - - </sect4> - - <sect4> - <title><makevar>DISTNAME</makevar></title> - - <para>You should set <makevar>DISTNAME</makevar> to be the base name of - your port. The default rules expect the distribution file - list (<makevar>DISTFILES</makevar>) to be - named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> by - default which, if it is a normal tarball, is going to be - something like <literal>foozolix-1.0.tar.gz</literal> for a setting of - <programlisting> -DISTNAME=foozolix-1.0</programlisting>.</para> - - <para>The default rules also expect the tarball(s) to extract - into a subdirectory called - <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para> - - <para>All this behavior can be overridden, of course, it simply - represents the most common time-saving defaults. For a port - requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a - subset of <makevar>DISTFILES</makevar> are - actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override - the <makevar>DISTFILES</makevar> list when - it comes to extraction, and the rest will be just left in - <makevar>DISTDIR</makevar> for later - use.</para> - - </sect4> - - <sect4> - <title><makevar>CATEGORIES</makevar></title> - - <para>When a package is created, it is put under - <filename>/usr/ports/packages/All</filename> and links are - made from one or more subdirectories of - <filename>/usr/ports/packages</filename>. The names of these - subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to - make life easier for the user when he is wading through the - pile of packages on the ftp site or the CD-ROM. Please take a - look at the existing categories (you can find them in <ulink - URL="http://www.freebsd.org/ports/">the ports - page</ulink>) and pick the ones that are suitable for your - port. If your port truly belongs to something that is - different from all the existing ones, you can even create a - new category name.</para> - - </sect4> - - <sect4> - <title><makevar>MASTER_SITES</makevar></title> - - <para>Record the directory part of the ftp/http-URL pointing at - the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the - trailing slash (<filename>/</filename>)!</para> - - <para>The <command>make</command> macros will try to use this specification for - grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it - already on the system.</para> - - <para>It is recommended that you put multiple sites on this - list, preferably from different continents. This will - safeguard against wide-area network problems, and we are even - planning to add support for automatically determining the - closest master site and fetching from there!</para> - - <para>If the original tarball is part of one of the following - popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or - Linux Sunsite, you refer to those sites in an easy compact - form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>, - <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and - <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the - path with in the archive. Here is an example:</para> - - <programlisting> -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> - - <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in - <filename>/etc/make.conf</filename> to override our choices, - and use their favorite mirrors of these popular archives - instead.</para> - - </sect4> - - <sect4 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></title> - - <para>If your port requires some additional patches that are - available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the - files and <makevar>PATCH_SITES</makevar> to - the URL of the directory that contains them (the format is the - same as <makevar>MASTER_SITES</makevar>).</para> - - <para>If the patch is not relative to the top of the source tree - (i.e., <makevar>WKRSRC</makevar>) because it - contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly. - For instance, if all the pathnames in the patch has an extra - <literal>foozolix-1.0/</literal> in front of the - filenames, then set - <literal>PATCH_DIST_STRIP=-p1</literal>.</para> - - <para>Do not worry if the patches are compressed, they will be - decompressed automatically if the filenames end with - <filename>.gz</filename> or - <filename>.Z</filename>.</para> - - <para>If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you can't just use - <makevar>PATCHFILES</makevar>. If that is - the case, add the name and the location of the patch tarball - to <makevar>DISTFILES</makevar> and - <makevar>MASTER_SITES</makevar>. Then, from - the <maketarget>pre-patch</maketarget> target, apply the - patch either by running the patch command from there, or - copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it - <filename>patch-<replaceable>xx</replaceable></filename>.</para> - - <note> - <para>Note the tarball will have been extracted alongside the - regular source by then, so there is no need to explicitly - extract it if it is a regular gzip'd or compress'd tarball. - If you do the latter, take extra care not to overwrite - something that already exists in that directory. Also do - not forget to add a command to remove the copied patch in - the <maketarget>pre-clean</maketarget> target.</para> - </note> - - </sect4> - - <sect4> - <title><makevar>MAINTAINER</makevar></title> - - <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para> - - <para>For detailed description of the responsibility of - maintainers, refer to <xref linkend="policies-maintainer" - remap="MAINTAINER - on Makefiles"> section.</para> - - </sect4> - - <sect4> - <title>Dependencies</title> - - <para>Many ports depend on other ports. There are five - variables that you can use to ensure that all the required - bits will be on the user's machine.</para> - - - <sect5> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>This variable specifies the shared libraries this port - depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable> pairs where - <replaceable>lib</replaceable> is the name of the shared library, - and <replaceable>dir</replaceable> is the directory in which to - find it in case it is not available. For example, - - <programlisting> -LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg</programlisting> - - will check for a shared jpeg library with - major version 6, and descend into the - <filename>graphics/jpeg</filename> subdirectory of your - ports tree to build and install it if it is not - found.</para> - - <note> - <para>The <replaceable>lib</replaceable> part is just an argument - given to <command>ldconfig -r | grep</command>, so - periods should be escaped by two backslashes like in the - example above.</para> - </note> - - <para>The dependency is checked from within the <maketarget>extract</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> will automatically install it if it - is not on the user's system.</para> - - </sect5> - - <sect5> - <title><makevar>RUN_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs where - <replaceable>path</replaceable> is the name of the executable or - file, and <replaceable>dir</replaceable> is the directory in which - to find it in case it is not available. If - <replaceable>path</replaceable> starts with a slash - (<literal>/</literal>), it is treated as a file and its - existence is tested with <command>test -e</command>; - otherwise, it is assumed to be an executable, and - <command>which -s</command> is used to determine if the - program exists in the user's search path.</para> - - <para>For example, - - <programlisting> -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish:${PORTSDIR}/x11/tk</programlisting> - - will check if the file - <filename>/usr/local/etc/innd</filename> exists, and build - and install it from the <filename>news/inn</filename> - subdirectory of the ports tree if it is not found. It will - also see if an executable called <command>wish</command> is in your search path, and - descend into the <filename>x11/tk</filename> subdirectory of - your ports tree to build and install it if it is not - found.</para> - - <note> - <para>In this case, <command>innd</command> is actually an - executable; if an executable is in a place that is not - expected to be in a normal user's search path, you should - use the full pathname.</para> - </note> - - <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> will automatically install it if it - is not on the user's system.</para> - - </sect5> - - <sect5> - <title><makevar>BUILD_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is - a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. - For example, - - <programlisting> -BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> - - will check for an executable called - <command>unzip</command>, and descend into the - <filename>archivers/unzip</filename> subdirectory of your - ports tree to build and install it if it is not - found.</para> - - <note> - <para>“build” here means everything from extracting to - compilation. The dependency is checked from within the - <maketarget>extract</maketarget> target.</para> - </note> - </sect5> - - <sect5> - <title><makevar>FETCH_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. For - example, - - <programlisting> -FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting> - - will check for an executable called - <command>ncftp2</command>, and descend into the - <filename>net/ncftp2</filename> subdirectory of your ports - tree to build and install it if it is not found.</para> - - <para>The dependency is checked from within the <maketarget>fetch</maketarget> target.</para> - - </sect5> - - <sect5> - <title><makevar>DEPENDS</makevar></title> - - <para>If there is a dependency that does not fall into either - of the above four categories, or your port requires to have - the source of the other port extracted (i.e., having them - installed is not enough), then use this variable. This is - just a list of directories, as there is nothing to check, - unlike the previous four.</para> - - </sect5> - </sect4> - - <sect4> - <title>Building mechanisms</title> - - <para>If your package uses GNU <command>make</command>, set - <literal>USE_GMAKE=yes</literal>. If your package uses GNU - <command>configure</command>, set - <literal>GNU_CONFIGURE=yes</literal>. If you want to give - some extra arguments to GNU <command>configure</command> (other than the default - <literal>--prefix=${PREFIX}</literal>), set those extra - arguments in <makevar>CONFIGURE_ARGS</makevar>.</para> - - <para>If your package is an X application that creates - <filename>Makefile</filename>s from - <filename>Imakefile</filename>s using <command>imake</command>, then set - <literal>USE_IMAKE=yes</literal>. This will cause the - configure stage to automatically do an <command>xmkmf - -a</command>. If the <option>-a</option> flag is a - problem for your port, set - <literal>XMKMF=xmkmf</literal>.</para> - - <para>If your port's source <filename>Makefile</filename> has - something else than <maketarget>all</maketarget> as the - main build target, set <makevar>ALL_TARGET</makevar> accordingly. Same - goes for <maketarget>install</maketarget> and <makevar>INSTALL_TARGET</makevar>.</para> - - </sect4> - - <sect4> - <title><makevar>NO_INSTALL_MANPAGES</makevar></title> - - <para>If the port uses <command>imake</command> but does not understand the - <filename>install.man</filename> target, - <literal>NO_INSTALL_MANPAGES=yes</literal> should be set. - In addition, the author of the original port should be shot. - <!-- smiley --><emphasis>:></emphasis></para> - - </sect4> - </sect3> - - <sect3> - <title>Ports that require Motif</title> - - <para>There are many programs that require a Motif library - (available from several commercial vendors, while there is (at - least) one effort to create a free clone) to compile. Since it - is a popular toolkit and their licenses usually permit - redistribution of statically linked binaries, we have made - special provisions for handling ports that require Motif in a - way that we can easily compile binaries linked either - dynamically or statically.</para> - - - <sect4> - <title><makevar>REQUIRES_MOTIF</makevar></title> - - <para>If your port requires Motif, define this variable in the - Makefile. This will prevent people who don't own a copy of - Motif from even attempting to build it.</para> - - </sect4> - - <sect4> - <title><makevar>MOTIFLIB</makevar></title> - - <para>This variable will be set by - <filename>bsd.port.mk</filename> to be the appropriate - reference to the Motif library. Please patch the source to - use this wherever the Motif library is referenced in the - Makefile or Imakefile.</para> - - <para>There are two common cases:</para> - - <orderedlist> - - <listitem> - <para>If the port refers to the Motif library as - <option>-lXm</option> in its Makefile or Imakefile, - simply substitute <makevar>MOTIFLIB</makevar> for it.</para> - </listitem> - - <listitem> - <para>If the port uses <literal>XmClientLibs</literal> in its Imakefile, - change it to <literal>${MOTIFLIB} - ${XTOOLLIB} ${XLIB}</literal>.</para> - </listitem> - - </orderedlist> - - <note> - <para><makevar>MOTIFLIB</makevar> (usually) - expands to <literal>-L/usr/X11R6/lib -lXm</literal> or - <literal>/usr/X11R6/lib/libXm.a</literal>, so there is - no need to add <option>-L</option> or - <option>-l</option> in front.</para> - </note> - </sect4> - </sect3> - - <sect3> - <title>Info files</title> - - <para>The new version of texinfo (included in 2.2.2-RELEASE and - onwards) contains a utility called <command>install-info</command> to add and delete entries to - the <filename>dir</filename> file. If your port installs any - info documents, please follow these instructions so your - port/package will correctly update the user's - <filename>${PREFIX}/info/dir</filename> file. (Sorry for - the length of this section, but it is imperative to weave all - the info files together. If done correctly, it will produce a - <emphasis>beautiful</emphasis> listing, so please bear with me! - <!-- smiley --><emphasis>:)</emphasis></para> - - <para>First, this is what you (as a porter) need to know:</para> - - <informalexample> - <screen>&prompt.user; <userinput>install-info --help</userinput> -install-info [OPTION]... [INFO-FILE [DIR-FILE]] - Install INFO-FILE in the Info directory file DIR-FILE. - -Options: ---delete Delete existing entries in INFO-FILE; - don't insert any new entries. - : ---entry=TEXT Insert TEXT as an Info directory entry. - : ---section=SEC Put this file's entries in section SEC of the directory. :</screen> - </informalexample> - - <note> - <para>This program will not actually - <emphasis>install</emphasis> info files; it merely inserts or - deletes entries in the <filename>dir</filename> file.</para> - </note> - - <para>Here's a seven-step procedure to convert ports to use - <command>install-info</command>. I will use - <filename>editors/emacs</filename> as an example.</para> - - <procedure> - <step> - <para>Look at the texinfo sources and make a patch to insert - <literal>@dircategory</literal> and <literal>@direntry</literal> - statements to files that don't have them. This is part of - my patch:</para> - - <programlisting> ---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 -+++ ./man/vip.texi Tue May 20 01:28:33 1997 -@@ -2,6 +2,10 @@ - - @setfilename ../info/vip - @settitle VIP -+@dircategory The Emacs editor and associated tools -+@direntry -+* VIP: (vip). A VI-emulation for Emacs. -+@end direntry - - @iftex - @finalout - :</programlisting> - - <para>The format should be self-explanatory. Many authors - leave a <filename>dir</filename> file in the source tree - that contains all the entries you need, so look around - before you try to write your own. Also, make sure you - look into related ports and make the section names and - entry indentations consistent (we recommend that all entry - text start at the 4th tab stop).</para> - - <note> - <para>Note that you can put only one info entry per file - because of a bug in <command>install-info - --delete</command> that deletes only the first entry - if you specify multiple entries in the - <email>@direntry</email> section.</para> - </note> - - <para>You can give the <literal>dir</literal> - entries to <command>install-info</command> as - arguments (<option>--section</option> and - <option>--entry</option>) instead of patching the texinfo - sources. I do not think this is a good idea for ports - because you need to duplicate the same information in - <emphasis>three</emphasis> places - (<filename>Makefile</filename> and - <literal>@exec</literal>/<literal>@unexec</literal> of - <filename>PLIST</filename>; see below). However, if you - have a Japanese (or other multibyte encoding) info files, - you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo - sources. (See <filename>Makefile</filename> and - <filename>PLIST</filename> of - <filename>japanese/skk</filename> for examples on how to - do this).</para> - </step> - - <step> - <para>Go back to the port directory and do a <command>make clean; make</command> and verify that - the info files are regenerated from the texinfo sources. - Since the texinfo sources are newer than the info files, - they should be rebuilt when you type <command>make</command>; but many - <filename>Makefile</filename>s don't include correct - dependencies for info files. In <command>emacs</command>' case, I had to - patch the main <filename>Makefile.in</filename> so it will - descend into the <filename>man</filename> - subdirectory to rebuild the info pages.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Tue Apr 15 00:15:28 1997 -@@ -184,7 +184,7 @@ - # Subdirectories to make recursively. `lisp' is not included - # because the compiled lisp files are part of the distribution - # and you cannot remake them without installing Emacs first. --SUBDIR = lib-src src -+SUBDIR = lib-src src man - - # The makefiles of the directories in $SUBDIR. - SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile ---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 -+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 -@@ -66,6 +66,7 @@ - ${srcdir}/gnu1.texi \ - ${srcdir}/glossary.texi - -+all: info - info: $(INFO_TARGETS) - - dvi: $(DVI_TARGETS)</programlisting> - - <para>The second hunk was necessary because the default - target in the <filename>man</filename> subdir is called - <maketarget>info</maketarget>, while the main - <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation - of the <filename>info</filename> info file - because we already have one with the same name in - <filename>/usr/share/info</filename> (that patch is not - shown here).</para> - </step> - - <step> - <para>If there is a place in the - <filename>Makefile</filename> that is installing the - <filename>dir</filename> file, delete it. Your - port may not be doing it. Also, remove any commands that - are otherwise mucking around with the - <filename>dir</filename> file.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Mon Apr 14 23:38:07 1997 -@@ -368,14 +368,8 @@ - if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ - then \ - (cd ${infodir}; \ -- if [ -f dir ]; then \ -- if [ ! -f dir.old ]; then mv -f dir dir.old; \ -- else mv -f dir dir.bak; fi; \ -- fi; \ - cd ${srcdir}/info ; \ -- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ -- (cd $${thisdir}; chmod a+r ${infodir}/dir); \ - for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ - (cd $${thisdir}; \ - ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ - chmod a+r ${infodir}/$$f); \</programlisting> - </step> - - <step> - <para>(This step is only necessary if you are modifying an - existing port.) Take a look at - <filename>pkg/PLIST</filename> and delete anything that is - trying to patch up <filename>info/dir</filename>. They - may be in <filename>pkg/INSTALL</filename> or some other - file, so search extensively.</para> - - <programlisting> -Index: pkg/PLIST -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v -retrieving revision 1.15 -diff -u -r1.15 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ PLIST 1997/04/15 06:32:12 -@@ -15,9 +15,6 @@ - man/man1/emacs.1.gz - man/man1/etags.1.gz - man/man1/ctags.1.gz --@unexec cp %D/info/dir %D/info/dir.bak --info/dir --@unexec cp %D/info/dir.bak %D/info/dir - info/cl - info/cl-1 - info/cl-2</programlisting> - </step> - - <step> - <para>Add a <maketarget>post-install</maketarget> - target to the <filename>Makefile</filename> to create a - <filename>dir</filename> file if it is not there. Also, - call <maketarget>install-info</maketarget> with the - installed info files.</para> - - <programlisting> -Index: Makefile -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/Makefile,v -retrieving revision 1.26 -diff -u -r1.26 Makefile ---- Makefile 1996/11/19 13:14:40 1.26 -+++ Makefile 1997/05/20 10:25:09 1.28 -@@ -20,5 +20,11 @@ - post-install: - .for file in emacs-19.34 emacsclient etags ctags b2m - strip ${PREFIX}/bin/${file} - .endfor -+ if [ ! -f ${PREFIX}/info/dir ]; then \ -+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \ -+ fi -+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode -+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir -+.endfor - - .include <bsd.port.mk></programlisting> - - <para>Do not use anything other than - <filename>/usr/share/info/dir</filename> and the above - command to create a new info file. In fact, I'd add the - first three lines of the above patch to - <filename>bsd.port.mk</filename> if you (the porter) - wouldn't have to do it in <filename>PLIST</filename> by - yourself anyway.</para> - </step> - - <step> - <para>Edit <filename>PLIST</filename> and add equivalent - <literal>@exec</literal> statements and also - <literal>@unexec</literal> for <command>pkg_delete</command>. - You do not need to delete <filename>info/dir</filename> - with <literal>@unexec</literal>.</para> - - <programlisting> -Index: pkg/PLIST -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v -retrieving revision 1.15 -diff -u -r1.15 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ PLIST 1997/05/20 10:25:12 1.17 -@@ -16,7 +14,15 @@ - man/man1/etags.1.gz - man/man1/ctags.1.gz -+@unexec install-info --delete %D/info/emacs %D/info/dir - : -+@unexec install-info --delete %D/info/ccmode %D/info/dir - info/cl - info/cl-1 -@@ -87,6 +94,18 @@ - info/viper-3 - info/viper-4 -+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir -+@exec install-info %D/info/emacs %D/info/dir - : -+@exec install-info %D/info/ccmode %D/info/dir - libexec/emacs/19.34/i386--freebsd/cvtmail - libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting> - - <note> - <para>The <literal>@unexec install-info - --delete</literal> commands have to be listed before - the info files themselves so they can read the files. - Also, the <literal>@exec install-info</literal> commands - have to be after the info files and the - <literal>@exec</literal> command that creates the the - <filename>dir</filename> file.</para> - </note> - </step> - - <step> - <para>Test and admire your work. <!-- smiley --><emphasis>:)</emphasis> The sequence I recommend is: - <command>make package</command>, - <command>pkg_delete</command>, then - <command>pkg_add</command>. Check the <filename>dir</filename> file before and after each - step.</para> - </step> - - </procedure> - - - </sect3> - - <sect3> - <title>Licensing Problems</title> - - <para>Some software packages have restrictive licenses or can be - in violation to the law (PKP's patent on public key crypto, ITAR - (export of crypto software) to name just two of them). What we - can do with them vary a lot, depending on the exact wordings of - the respective licenses.</para> - - <note> - <para>It is your responsibility as a porter to read the - licensing terms of the software and make sure that the FreeBSD - project will not be held accountable of violating them by - redistributing the source or compiled binaries either via ftp - or CD-ROM. If in doubt, please contact the &a.ports;.</para> - </note> - - <para>There are two variables you can set in the Makefile to - handle the situations that arise frequently:</para> - - - <orderedlist> - - <listitem> - <para>If the port has a “do not sell for profit” type of - license, set the variable <makevar>NO_CDROM</makevar>. We - will make sure such ports won't go into the CD-ROM come - release time. The distfile and package will still be - available via ftp.</para> - </listitem> - - <listitem> - <para>If the resulting package needs to be built uniquely - for each site, or the resulting binary package can't be - distributed due to licensing; set the variable - <makevar>NO_PACKAGE</makevar>. We will make sure such - packages won't go on the ftp site, nor into the CD-ROM - come release time. The distfile will still be included on - both however.</para> - </listitem> - - <listitem> - <para>If the port has legal restrictions on who can use it - (e.g., crypto stuff) or has a “no commercial use” license, - set the variable <makevar>RESTRICTED</makevar> to be the - string describing the reason why. For such ports, the - distfiles/packages will not be available even from our ftp - sites.</para> - </listitem> - - </orderedlist> - - - <note> - <para>The GNU General Public License (GPL), both version 1 - and 2, should not be a problem for ports.</para> - </note> - - <note> - <para>If you are a committer, make sure you update the - <filename>ports/LEGAL</filename> file too.</para> - </note> - </sect3> - - <sect3> - <title>Upgrading</title> - - <para>When you notice that a port is out of date compared to the - latest version from the original authors, first make sure you - have the latest port. You can find them in the - <filename>ports-current</filename> directory of the ftp mirror - sites.</para> - - <para>The next step is to send a mail to the maintainer, if one is - listed in the port's <filename>Makefile</filename>. That person may already be - working on an upgrade, or have a reason to not upgrade the port - right now (because of, for example, stability problems of the - new version).</para> - - <para>If the maintainer asks you to do the upgrade or there isn't - any such person to begin with, please make the upgrade and send - the recursive diff (either unified or context diff is fine, but - port committers appear to prefer unified diff more) of the new - and old ports directories to us (i.e., if your modified ports - directory is called <filename>superedit</filename> - and the original as in our tree is - <filename>superedit.bak</filename>, then send us the result of - <command>diff -ruN superedit.bak - superedit</command>). Please examine the output to make - sure all the changes make sense. The best way to send us the - diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> - (category <literal>ports</literal>). Please mention any added or deleted files - in the message, as they have to be explicitly specified to CVS - when doing a commit. If the diff is more than about 20KB, please - compress and uuencode it; otherwise, just include it in as is in - the PR.</para> - - </sect3> - - <sect3> - <title>Do's and Dont's</title> - - <para>Here is a list of common do's and dont's that you encounter - during the porting process.</para> - - - <sect4> - <title><makevar>WRKDIR</makevar></title> - - <para>Do not leave anything valuable lying around in the - <filename>work</filename> subdirectory, <command>make clean</command> will - <emphasis>nuke</emphasis> it completely! If you need - auxiliary files that are not scripts or patches, put them in - the <makevar>FILESDIR</makevar> subdirectory - (<filename>files</filename> by default) and use the - <maketarget>post-extract</maketarget> target to copy them - to the <filename>work</filename> subdirectory.</para> - - </sect4> - - <sect4> - <title>Package information</title> - - <para>Do include package information, i.e. - <filename>COMMENT</filename>, <filename>DESCR</filename>, and - <filename>PLIST</filename>, in <filename>pkg</filename>.</para> - - <note> - <para>Note that these files are not used only for packaging - anymore, and are <emphasis>mandatory</emphasis> now, even if - <makevar>NO_PACKAGE</makevar> is - set.</para> - </note> - </sect4> - - <sect4> - <title>Compress manpages, strip binaries</title> - - <para>Do compress manpages and strip binaries. If the original - source already strips the binary, fine; otherwise, you can add - a <maketarget>post-install</maketarget> rule to do it - yourself. Here is an example:</para> - - <programlisting> -post-install: - strip ${PREFIX}/bin/xdl</programlisting> - - <para>Use the <command>file</command> command on the - installed executable to check whether the binary is stripped - or not. If it does not say `not stripped', it is - stripped.</para> - - <para>To automagically compress the manpages, use the <makevar>MAN[1-9LN]</makevar> - variables. They will check the variable - <makevar>NOMANCOMPRESS</makevar> that the user can set in - <filename>/etc/make.conf</filename> to disable man page - compression. Place them last in the section below the - <makevar>MAINTAINER</makevar> variable. Here is an example:</para> - - <programlisting> -MAN1= foo.1 bar.1 -MAN5= foo.conf.5 -MAN8= baz.8</programlisting> - - <note> - <para>This is not usually necessary with ports that are X - applications and use Imake to build.</para> - </note> - - <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use the - <makevar>MANPREFIX</makevar> to set it. Also, if only manpages - in certain section go in a non-standard place, such as many - Perl modules ports, you can set individual man paths using - <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> - (where <replaceable>sect</replaceable> is one of 1-9, L or - N).</para> - - </sect4> - - <sect4> - <title><makevar>INSTALL_*</makevar> macros</title> - - <para>Do use the macros provided in - <filename>bsd.port.mk</filename> to ensure correct modes and - ownership of files in your own *-install targets. They - are:</para> - - - <itemizedlist> - - <listitem> - <para><makevar>${INSTALL_PROGRAM}</makevar> is - a command to install binary executables.</para> - </listitem> - - <listitem> - <para><makevar>${INSTALL_SCRIPT}</makevar> is a - command to install executable scripts.</para> - </listitem> - - <listitem> - <para><makevar>${INSTALL_DATA}</makevar> is a - command to install sharable data.</para> - </listitem> - - <listitem> - <para><makevar>${INSTALL_MAN}</makevar> is a - command to install manpages and other documentation (it - doesn't compress anything).</para> - </listitem> - - </itemizedlist> - - - <para>These are basically the <command>install</command> command with all the appropriate - flags. See below for an example on how to use them.</para> - - </sect4> - - <sect4> - <title><filename>INSTALL</filename> package script</title> - - <para>If your port needs execute commands when the binary - package is installed with pkg_add you can do with via the - <filename>pkg/INSTALL</filename> script. This script will - automatically be added to the package, and will be run twice - by pkg_add. The first time will as <command>INSTALL ${PKGNAME} PRE-INSTALL</command> and the - second time as <command>INSTALL ${PKGNAME} - POST-INSTALL</command>. <literal>$2</literal> can be tested to determine which - mode the script is being run in. The - <envar>PKG_PREFIX</envar> environmental variable will be - set to the package installation directory. See man - <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for additional - information.</para> - - <note> - <para>This script is not run automatically if you install the - port with <command>make install</command>. If you are - depending on it being run, you will have to explicitly call - it on your port's <filename>Makefile</filename>.</para> - </note> - </sect4> - - <sect4> - <title><filename>REQ</filename> package script</title> - - <para>If your port needs to determine if it should install or - not, you can create a <filename>pkg/REQ</filename> - “requirements” script. It will be invoked automatically at - installation/deinstallation time to determine whether or not - installation/deinstallation should proceed. See man - <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> and man - <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information.</para> - - </sect4> - - <sect4> - <title>Install additional documentation</title> - - <para>If your software has some documentation other than the - standard man and info pages that you think is useful for the - user, install it under - <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be - done, like the previous item, in the <maketarget>post-install</maketarget> target.</para> - - <para>Create a new directory for your port. The directory name - should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part. - However, if you think the user might want different versions - of the port to be installed at the same time, you can use the - whole <makevar>PKGNAME</makevar>.</para> - - <para>Make the installation dependent to the variable - <makevar>NOPORTDOCS</makevar> so that users can disable it in - <filename>/etc/make.conf</filename>, like this:</para> - - <programlisting> -post-install: -.if !defined(NOPORTDOCS) - ${MKDIR}${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv -.endif</programlisting> - - <para>Do not forget to add them to - <filename>pkg/PLIST</filename> too! (Do not worry about - <makevar>NOPORTDOCS</makevar> here; there is currently no way - for the packages to read variables from - <filename>/etc/make.conf</filename>.)</para> - - <para>If you need to display a message to the installer, you may - place the message in <filename>pkg/MESSAGE</filename>. This - capibility is often useful to display additional installation - steps to be taken after a pkg_add, or to display licensing - information.</para> - - <note> - <para><filename>MESSAGE</filename> does not need to be added - to <filename>pkg/PLIST</filename>).</para> - </note> - </sect4> - - <sect4> - <title><makevar>DIST_SUBDIR</makevar></title> - - <para>Do not let your port clutter - <filename>/usr/ports/distfiles</filename>. If your port - requires a lot of files to be fetched, or contains a file that - has a name that might conflict with other ports (e.g., - <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the - port (<makevar>PKGNAME</makevar> without the - version part should work fine). This will change <makevar>DISTDIR</makevar> from the default - <filename>/usr/ports/distfiles</filename> to - <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>, - and in effect puts everything that is required for your port - into that subdirectory.</para> - - <para>It will also look at the subdirectory with the same name - on the backup master site at - <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your - <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para> - - <note> - <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your - Makefile.</para> - </note> - </sect4> - - <sect4> - <title>Feedback</title> - - <para>Do send applicable changes/patches to the original - author/maintainer for inclusion in next release of the code. - This will only make your job that much easier for the next - release.</para> - - </sect4> - - <sect4> - <title>RCS strings</title> - - <para>Do not put RCS strings in patches. CVS will mangle them - when we put the files into the ports tree, and when we check - them out again, they will come out different and the patch - will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with - <literal>$Id</literal> or <literal>$RCS</literal>.</para> - - </sect4> - - <sect4> - <title>Recursive diff</title> - - <para>Using the recurse (<option>-r</option>) option to - <command>diff</command> to generate patches is - fine, but please take a look at the resulting patches to make - sure you don't have any unnecessary junk in there. In - particular, diffs between two backup files, <filename>Makefiles</filename> when the - port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and - should be deleted. Also, if you had to delete a file, then you - can do it in the <maketarget>post-extract</maketarget> - target rather than as part of the patch. Once you are happy - with the resuling diff, please split it up into one source - file per patch file.</para> - - </sect4> - - <sect4> - <title><makevar>PREFIX</makevar></title> - - <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this - variable will be set to <makevar>LOCALBASE</makevar> (default - <filename>/usr/local</filename>), unless <makevar>USE_IMAKE</makevar> or <makevar>USE_X11</makevar> is set, in which case it - will be <makevar>X11BASE</makevar> (default - <filename>/usr/X11R6</filename>).)</para> - - <para>Not hard-coding <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename> anywhere in the source will - make the port much more flexible and able to cater to the - needs of other sites. For X ports that use <command>imake</command>, this is - automatic; otherwise, this can often be done by simply - replacing the occurrences of <filename>/usr/local</filename> - (or <filename>/usr/X11R6</filename> for X ports that do not - use imake) in the various scripts/Makefiles in the port to - read <makevar>PREFIX</makevar>, as this - variable is automatically passed down to every stage of the - build and install processes.</para> - - <para>The variable <makevar>PREFIX</makevar> - can be reassigned in your Makefile or in the user's - environment. However, it is strongly discouraged for - individual ports to set this variable explicitly in the - Makefiles. (If your port is an X port but does not use <command>imake</command>, - set <literal>USE_X11=yes</literal>; this is quite different - from setting <literal>PREFIX=/usr/X11R6</literal>.)</para> - - <para>Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For - instance, if your port requires a macro - <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag: - - <programlisting> --DPAGER=\"${PREFIX}/bin/less\"</programlisting> - - or - - <programlisting> --DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - - if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para> - - </sect4> - - <sect4> - <title>Subdirectories</title> - - <para>Try to let the port put things in the right subdirectories - of <makevar>PREFIX</makevar>. Some ports - lump everything and put it in the subdirectory with the port's - name, which is incorrect. Also, many ports put everything - except binaries, header files and manual pages in the a - subdirectory of <filename>lib</filename>, which does not - bode well with the BSD paradigm. Many of the files should be - moved to one of the following: <filename>etc</filename> - (setup/configuration files), <filename>libexec</filename> - (executables started internally), <filename>sbin</filename> - (executables for superusers/managers), - <filename>info</filename> (documentation for info browser) - or <filename>share</filename> (architecture independent - files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details, the rule governing <filename>/usr</filename> pretty - much applies to <filename>/usr/local</filename> too. The - exception are ports dealing with USENET “news”. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a destination for - their files.</para> - - </sect4> - - <sect4> - <title>ldconfig</title> - - <para>If your port installs a shared library, add a <maketarget>post-install</maketarget> target to your Makefile - that runs <command>/sbin/ldconfig -m</command> on - the directory where the new library is installed (usually - <filename><makevar>PREFIX</makevar>/lib</filename>) to register it into - the shared library cache.</para> - - <para>Also, add an <literal>@exec</literal> line to your - <filename>pkg/PLIST</filename> file so that a user who - installed the package can start using the shared library - immediately. This line should immediately follow the line - for the shared library itself, as in:</para> - - <programlisting> -lib/libtcl80.so.1.0 -@exec /sbin/ldconfig -m %D/lib</programlisting> - - <para>Never, ever, <emphasis>ever</emphasis> add a line that - says <command>ldconfig</command> without any - arguments to your <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. This will reset the - shared library cache to the contents of - <filename>/usr/lib</filename> only, and will royally screw up - the user's machine (“Help, xinit does not run anymore after I - install this port!”). Anybody who does this will be shot and - cut into 65,536 pieces by a rusty knife and have his liver - chopped out by a bunch of crows and will eternally rot to - death in the deepest bowels of hell (not necessarily in that - order)....</para> - - </sect4> - - <sect4> - <title>UIDs</title> - - <para>If your port requires a certain user ID to be on the - installed system, let the <filename>pkg/INSTALL</filename> - script call <command>pw</command> to create it - automatically. Look at <filename>japanese/Wnn</filename> or - <filename>net/cvsup-mirror</filename> for examples. It is - customary to use UIDs in the upper 2-digit range (i.e., from - around 50 to 99) for this purpose.</para> - - <para>Make sure you don't use a UID already used by the system - or other ports. This is the current list of UIDs between 50 - and 99.</para> - - <programlisting> -majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent -cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent -gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh -uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico -xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent -pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent -wnn:*:69:7:Wnn:/nonexistent:/nonexistent -ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent -pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh -ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent -alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent -qmaill:*:83:81:QMail user:/var/qmail:/nonexistent -qmaild:*:82:81:QMail user:/var/qmail:/nonexistent -qmailq:*:85:82:QMail user:/var/qmail:/nonexistent -qmails:*:87:82:QMail user:/var/qmail:/nonexistent -qmailp:*:84:81:QMail user:/var/qmail:/nonexistent -qmailr:*:86:82:QMail user:/var/qmail:/nonexistent -msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting> - - <para>Please send a notice to &a.ports; if you submit or commit - a port that allocates a new UID in this range so we can keep - this list up to date.</para> - - </sect4> - - <sect4> - <title>If you are stuck....</title> - - <para>Do look at existing examples and the - <filename>bsd.port.mk</filename> file before asking us - questions! <!-- smiley --><emphasis>;)</emphasis></para> - - <para>Do ask us questions if you have any trouble! Do not just - beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para> - - </sect4> - </sect3> - - <sect3 id="porting-samplem"> - <title>A Sample <filename>Makefile</filename></title> - - <para>Here is a sample <filename>Makefile</filename> that you can - use to create a new port. Make sure you remove all the extra - comments (ones between brackets)!</para> - - <para>It is recommended that you follow this format (ordering of - variables, empty lines between sections, etc.). Not all of the - existing <filename>Makefile</filename>s are in this format - (mostly old ones), but we are trying to uniformize how they - look. This format is designed so that the most important - information is easy to locate.</para> - - <programlisting> -[the header...just to make it easier for us to identify the ports.] -# New ports collection makefile for: xdvi -[the version required header should updated when upgrading a port.] -# Version required: pl18 [things like "1.5alpha" are fine here too] -[this is the date when the first version of this Makefile was created. -Never change this when doing an update of the port.] -# Date created: 26 May 1995 -[this is the person who did the original port to FreeBSD, in particular, the -person who wrote the first version of this Makefile. Remember, this should -not be changed when upgrading the port later.] -# Whom: Satoshi Asami <asami@FreeBSD.ORG> -# -# $Id$ -[ ^^^^ This will be automatically replaced with RCS ID string by CVS -when it is committed to our repository.] -# - -[section to describe the port itself and the master site - DISTNAME - is always first, followed by PKGNAME (if necessary), CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - After those, one of EXTRACT_SUFX or DISTFILES can be specified too.] -DISTNAME= xdvi -PKGNAME= xdvi-pl18 -CATEGORIES= print -[do not forget the trailing slash ("/")! - if you aren't using MASTER_SITE_* macros] -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications -[set this if the source is not in the standard ".tar.gz" form] -EXTRACT_SUFX= .tar.Z - -[section for distributed patches -- can be empty] -PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ -PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz - -[maintainer; *mandatory*! This is the person (preferably with commit - privileges) who a user can contact for questions and bug reports - this - person should be the porter or someone who can forward questions to the - original porter reasonably promptly. If you really do not want to have - your address here, set it to "ports@FreeBSD.ORG".] -MAINTAINER= asami@FreeBSD.ORG - -[dependencies -- can be empty] -RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript -LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm - -[this section is for other standard bsd.port.mk variables that do not - belong to any of the above] -[If it asks questions during configure, build, install...] -IS_INTERACTIVE= yes -[If it extracts to a directory other than ${DISTNAME}...] -WRKSRC= ${WRKDIR}/xdvi-new -[If the distributed patches were not made relative to ${WRKSRC}, you - may need to tweak this] -PATCH_DIST_STRIP= -p1 -[If it requires a "configure" script generated by GNU autoconf to be run] -GNU_CONFIGURE= yes -[If it requires GNU make, not /usr/bin/make, to build...] -USE_GMAKE= yes -[If it is an X application and requires "xmkmf -a" to be run...] -USE_IMAKE= yes -[et cetera.] - -[non-standard variables to be used in the rules below] -MY_FAVORITE_RESPONSE= "yeah, right" - -[then the special rules, in the order they are called] -pre-fetch: - i go fetch something, yeah - -post-patch: - i need to do something after patch, great - -pre-install: - and then some more stuff before installing, wow - -[and then the epilogue] -.include <bsd.port.mk></programlisting> - - </sect3> - - <sect3> - <title>Package Names</title> - - <para>The following are the conventions you should follow in - naming your packages. This is to have our package directory - easy to scan, as there are already lots and lots of packages and - users are going to turn away if they hurt their eyes!</para> - - <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para> - - <para>If your <makevar>DISTNAME</makevar> - doesn't look like that, set <makevar>PKGNAME</makevar> to something in that - format.</para> - - - <orderedlist> - - <listitem> - <para>FreeBSD strives to support the native language of its - users. The <replaceable>language-</replaceable> part should be a two letter - abbreviation of the natural language defined by ISO-639 if - the port is specific to a certain language. Examples are - <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese, - <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para> - </listitem> - - <listitem> - <para>The <filename>name</filename> part - should be all lowercases, except for a really large - package (with lots of programs in it). Things like - XFree86 (yes there really is a package of it, check it - out) and ImageMagick fall into this category. Otherwise, - convert the name (or at least the first letter) to - lowercase. If the software in question really is called - that way, you can have numbers, hyphens and underscores in - the name too (like <literal>kinput2</literal>).</para> - </listitem> - - <listitem> - <para>If the port can be built with different hardcoded - defaults (usually specified as environment variables or on - the <command>make</command> command line), the - <replaceable>-compiled.specifics</replaceable> part should state the - compiled-in defaults (the hyphen is optional). Examples - are papersize and font units.</para> - </listitem> - - <listitem> - <para>The version string should be a period-separated list - of integers and single lowercase alphabetics. The only - exception is the string <literal>pl</literal> (meaning `patchlevel'), which - can be used <emphasis>only</emphasis> when there are no - major and minor version numbers in the software.</para> - </listitem> - - </orderedlist> - - - <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Distribution Name</entry> - <entry>Package Name</entry> - <entry>Reason</entry> - </row> - </thead> - - <tbody> - <row> - <entry>mule-2.2.2.</entry> - <entry>mule-2.2.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>XFree86-3.1.2</entry> - <entry>XFree86-3.1.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>EmiClock-1.0.2</entry> - <entry>emiclock-1.0.2</entry> - <entry>No uppercase names for single programs</entry> - </row> - - <row> - <entry>gmod1.4</entry> - <entry>gmod-1.4</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>xmris.4.0.2</entry> - <entry>xmris-4.0.2</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>rdist-1.3alpha</entry> - <entry>rdist-1.3a</entry> - <entry>No strings like <literal>alpha</literal> - allowed</entry> - </row> - - <row> - <entry>es-0.9-beta1</entry> - <entry>es-0.9b1</entry> - <entry>No strings like <literal>beta</literal> - allowed</entry> - </row> - - <row> - <entry>v3.3beta021.src</entry> - <entry>tiff-3.3</entry> - <entry>What the heck was that anyway?</entry> - </row> - - <row> - <entry>tvtwm</entry> - <entry>tvtwm-pl11</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>piewm</entry> - <entry>piewm-1.0</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>xvgr-2.10pl1</entry> - <entry>xvgr-2.10.1</entry> - <entry><literal>pl</literal> allowed only when no - major/minor version numbers</entry> - </row> - - <row> - <entry>gawk-2.15.6</entry> - <entry>ja-gawk-2.15.6</entry> - <entry>Japanese language version</entry> - </row> - - <row> - <entry>psutils-1.13</entry> - <entry>psutils-letter-1.13</entry> - <entry>Papersize hardcoded at package build time</entry> - </row> - - <row> - <entry>pkfonts</entry> - <entry>pkfonts300-1.0</entry> - <entry>Package for 300dpi fonts</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If there is absolutely no trace of version information in - the original source and it is unlikely that the original author - will ever release another version, just set the version string - to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the - original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the - version.</para> - - </sect3> - - <sect3> - <title>That is It, Folks!</title> - - <para>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really.</para> - - <para>Well, now that you know how to do a port, let us go at it - and convert everything in the world into ports! That is the - easiest way to start contributing to the FreeBSD Project! - <!-- smiley --><emphasis>:)</emphasis></para> - - </sect3> - </sect2> - - <sect2> - <title>Money, Hardware or Internet access</title> - - <para>We are always very happy to accept donations to further the - cause of the FreeBSD Project and, in a volunteer effort like ours, - a little can go a long way! Donations of hardware are also very - important to expanding our list of supported peripherals since we - generally lack the funds to buy such items ourselves.</para> - - - <sect3> - <title>Donating funds</title> - - <para>While the FreeBSD Project is not a 501(C3) (non-profit) - corporation and hence cannot offer special tax incentives for - any donations made, any such donations will be gratefully - accepted on behalf of the project by FreeBSD, Inc.</para> - - <para>FreeBSD, Inc. was founded in early 1995 by &a.jkh; and - &a.davidg; with the goal of furthering the aims of the FreeBSD - Project and giving it a minimal corporate presence. Any and all - funds donated (as well as any profits that may eventually be - realized by FreeBSD, Inc.) will be used exclusively to further - the project's goals.</para> - - <para>Please make any checks payable to FreeBSD, Inc., sent in - care of the following address:</para> - - <address> - <otheraddr>FreeBSD, Inc.</otheraddr> - <otheraddr>c/o Jordan Hubbard</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city> - <state>CA</state>, <postcode>94520</postcode> - </address> - - <para>Wire transfers may also be sent directly to:</para> - - <address> - <otheraddr>Bank Of America</otheraddr> - <otheraddr>Concord Main Office</otheraddr> - <pob>P.O. Box 37176</pob> - <city>San Francisco</city> - <state>CA</state>, <postcode>94137-5176</postcode> - - <otheraddr>Routing #: 121-000-358</otheraddr> - <otheraddr>Account #: 01411-07441 (FreeBSD, Inc.)</otheraddr> - </address> - - <para>Any correspondence related to donations should be sent to - Jordan Hubbard <email>jkh@FreeBSD.org</email>, - either via email or to the FreeBSD, Inc. postal address given - above.</para> - - <para>If you do not wish to be listed in our <xref - linkend="donors" remap="donors"> section, please specify this - when making your donation. Thanks!</para> - - </sect3> - - <sect3> - <title>Donating hardware</title> - - <para>Donations of hardware in any of the 3 following categories - are also gladly accepted by the FreeBSD Project:</para> - - - <itemizedlist> - - <listitem> - <para>General purpose hardware such as disk drives, memory - or complete systems should be sent to the FreeBSD, Inc. - address listed in the <emphasis>donating funds</emphasis> - section.</para> - </listitem> - - <listitem> - <para>Hardware for which ongoing compliance testing is - desired. We are currently trying to put together a testing - lab of all components that FreeBSD supports so that proper - regression testing can be done with each new release. We - are still lacking many important pieces (network cards, - motherboards, etc) and if you would like to make such a - donation, please contact &a.davidg; for information on - which items are still required.</para> - </listitem> - - <listitem> - <para>Hardware currently unsupported by FreeBSD for which - you would like to see such support added. Please contact - the &a.core; before sending such items as we will need to - find a developer willing to take on the task before we can - accept delivery of new hardware.</para> - </listitem> - - </itemizedlist> - - - </sect3> - - <sect3> - <title>Donating Internet access</title> - - <para>We can always use new mirror sites for FTP, WWW or <command>cvsup</command>. If - you would like to be such a mirror, please contact the FreeBSD project - administrators <email>admin@FreeBSD.ORG</email> for more information.</para> - - </sect3> - </sect2> - </sect1> - - <sect1 id="donors"> - <title>Donors Gallery</title> - - <para>The FreeBSD Project is indebted to the following donors and - would like to publically thank them here!</para> - - - <itemizedlist> - - <listitem> - <para><emphasis>Contributors to the central server - project:</emphasis></para> - - <para>The following individuals and businesses made it possible - for the FreeBSD Project to build a new central server machine - to eventually replace - <hostid role="fqdn">freefall.freebsd.org</hostid> by donating the - following items:</para> - - - <itemizedlist> - - <listitem> - <para>Ade - Barkah <email>mbarkah@freebsd.org</email> and his employer, <ulink - URL="http://www.hemi.com">Hemisphere Online</ulink>, - donated a <emphasis>Pentium Pro (P6) 200Mhz - CPU</emphasis></para> - </listitem> - - <listitem> - <para><ulink URL="http://www.asacomputers.com">ASA - Computers</ulink> donated a <emphasis>Tyan - 1662 motherboard</emphasis>.</para> - </listitem> - - <listitem> - <para>Joe McGuckin <email>joe@via.net</email> - of <ulink URL="http://www.via.net">ViaNet - Communications</ulink> donated a <emphasis>Kingston ethernet controller.</emphasis></para> - </listitem> - - <listitem> - <para>Jack - O'Neill <email>jack@diamond.xtalwind.net</email> donated an <emphasis>NCR - 53C875 SCSI controller card</emphasis>.</para> - </listitem> - - <listitem> - <para>Ulf - Zimmermann <email>ulf@Alameda.net</email> of <ulink - URL="http://www.Alameda.net">Alameda Networks</ulink> - donated <emphasis>128MB of memory</emphasis>, a - <emphasis>4 Gb disk drive and the - case.</emphasis></para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para><emphasis>Direct funding:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed direct funding to the project:</para> - - - <itemizedlist> - - <listitem> - <para>Annelise - Anderson <email>ANDRSN@HOOVER.STANFORD.EDU</email></para> - </listitem> - - <listitem> - <para>Matt - Dillon <email>dillon@best.net</email></para> - </listitem> - - <listitem> - <para><ulink URL="http://www.epilogue.com/">Epilogue - Technology Corporation</ulink></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan</para> - </listitem> - - <listitem> - <para>Gianmarco - Giovannelli <email>gmarco@masternet.it</email></para> - </listitem> - - <listitem> - <para>Josef C. - Grosch <email>joeg@truenorth.org</email></para> - </listitem> - - <listitem> - <para>Chuck - Robey <email>chuckr@freebsd.org</email></para> - </listitem> - - <listitem> - <para>Kenneth - P. Stox <email>ken@stox.sa.enteract.com</email> of <ulink - URL="http://www.imagescape.com">Imaginary Landscape, - LLC.</ulink></para> - </listitem> - - <listitem> - <para>Dmitry S. - Kohmanyuk <email>dk@dog.farm.org</email></para> - </listitem> - - <listitem> - <para><ulink URL="http://www.cdrom.co.jp/">Laser5</ulink> - of Japan (a portion of the profits from sales of their - various FreeBSD CD-ROMs.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.mmjp.or.jp/fuki/">Fuki - Shuppan Publishing Co.</ulink> donated a portion of - their profits from <emphasis>Hajimete no - FreeBSD</emphasis> (FreeBSD, Getting started) to the - FreeBSD and XFree86 projects.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.ascii.co.jp/">ASCII - Corp.</ulink> donated a portion of their profits from - several FreeBSD-related books to the FreeBSD - project.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.yokogawa.co.jp/">Yokogawa - Electric Corp</ulink> has generously donated - significant funding to the FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink - URL="http://www.buffnet.net/">BuffNET</ulink></para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para><emphasis>Hardware contributors:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support:</para> - - - <itemizedlist> - - <listitem> - <para>Walnut Creek CDROM for providing the Pentium P5-90 - and 486/DX2-66 EISA/VL systems that are being used for - our development work, to say nothing of the network - access and other donations of hardware resources.</para> - </listitem> - - <listitem> - <para>TRW Financial Systems, Inc. provided 130 PCs, three - 68 GB fileservers, twelve Ethernets, two routers and an - ATM switch for debugging the diskless code. They also - keep a couple of FreeBSD hackers alive and busy. - Thanks!</para> - </listitem> - - <listitem> - <para>Dermot McDonnell donated the Toshiba XM3401B CDROM - drive currently used in freefall.</para> - </listitem> - - <listitem> - <para>&a.chuck; contributed his floppy tape streamer for - experimental work.</para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;, provided Wangtek and Archive QIC-02 tape drives in order to improve the <devicename>wt</devicename> driver.</para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. <!-- smiley -->;-)</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.tekram.com">Tekram - Technologies</ulink> sent one each of their DC-390, - DC-390U and DC-390F FAST and ULTRA SCSI host adapter - cards for regression testing of the NCR and AMD drivers - with their cards. They are also to be applauded for - making driver sources for free operating systems - available from their FTP server <ulink - URL="ftp://ftp.tekram.com/scsi/FreeBSD">ftp://ftp.tekram.com/scsi/FreeBSD</ulink>.</para> - </listitem> - - <listitem> - <para><email>Larry M. - Augustin</email> contributed not only a Symbios - Sym8751S SCSI card, but also a set of data books, - including one about the forthcoming Sym53c895 chip with - Ultra-2 and LVD support, and the latest programming - manual with information on how to safely use the - advanced features of the latest Symbios SCSI chips. - Thanks a lot!</para> - </listitem> - - <listitem> - <para>Christoph - Kukulies <email>kuku@freebsd.org</email> donated an FX120 12 speed Mitsumi - CDROM drive for IDE CDROM driver development.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para><emphasis>Special contributors:</emphasis></para> - - - <itemizedlist> - - <listitem> - <para><ulink URL="http://www.cdrom.com">Walnut Creek - CDROM</ulink> has donated almost more than we can say - (see the - <xref linkend="history" remap="history"> document for - more details). In particular, we would like to thank - them for the original hardware used for - <hostid role="fqdn">freefall.FreeBSD.ORG</hostid>, our primary - development machine, and for - <hostid role="fqdn">thud.FreeBSD.ORG</hostid>, a testing and - build box. We are also indebted to them for funding - various contributors over the years and providing us - with unrestricted use of their T1 connection to the - Internet.</para> - </listitem> - - <listitem> - <para>The <ulink - URL="http://www.interface-business.de">interface - business GmbH, Dresden</ulink> has been patiently - supporting &a.joerg; who has often preferred FreeBSD - work over paywork, and used to fall back to their (quite - expensive) EUnet Internet connection whenever his - private connection became too slow or flakey to work - with it...</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.bsdi.com">Berkeley Software - Design, Inc.</ulink> has contributed their DOS - emulator code to the remaining BSD world, which is used - in the <emphasis>dosemu</emphasis> command.</para> - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - - </sect1> - - <sect1> - <title>Derived Software Contributors</title> - - <para>This software was originally derived from William F. Jolitz's - 386BSD release 0.1, though almost none of the original 386BSD - specific code remains. This software has been essentially - re-implemented from the 4.4BSD-Lite release provided by the Computer - Science Research Group (CSRG) at the University of California, - Berkeley and associated academic contributors.</para> - - <para>There are also portions of NetBSD that have been integrated into - FreeBSD as well, and we would therefore like to thank all the - contributors to NetBSD for their work.</para> - - </sect1> - - <sect1 id="contrib-additional"> - <title>Additional FreeBSD Contributors</title> - - <para>(in alphabetical order by first name):</para> - - - <itemizedlist> - - <listitem> - <para>A JOSEPH KOSHY <email>koshy@india.hp.com</email></para> - </listitem> - - <listitem> - <para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>Ada T Lim <email>ada@bsd.org</email></para> - </listitem> - - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian T. Filipi-Martin <email>atf3r@agate.cs.virginia.edu</email></para> - </listitem> - - <listitem> - <para>Akito Fujita <email>fujita@zoo.ncl.omron.co.jp</email></para> - </listitem> - - <listitem> - <para>Alain Kalker <email>A.C.P.M.Kalker@student.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Alan Cox <email>alc@cs.rice.edu</email></para> - </listitem> - - <listitem> - <para>Andreas Kohout <email>shanee@rabbit.augusta.de</email></para> - </listitem> - - <listitem> - <para>Andreas Lohr <email>andreas@marvin.RoBIN.de</email></para> - </listitem> - - <listitem> - <para>Andrew Gordon <email>andrew.gordon@net-tel.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew McRae <email>amcrae@cisco.com</email></para> - </listitem> - - <listitem> - <para>Andrew Moore <email>alm@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Andrew Stevenson <email>andrew@ugh.net.au</email></para> - </listitem> - - <listitem> - <para>Andrew V. Stesin <email>stesin@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrey Zakhvatov <email>andy@icc.surw.chel.su</email></para> - </listitem> - - <listitem> - <para>Andy Whitcroft <email>andy@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Angelo Turetta <email>ATuretta@stylo.it</email></para> - </listitem> - - <listitem> - <para>Anthony Yee-Hang Chan <email>yeehang@netcom.com</email></para> - </listitem> - - <listitem> - <para>Ari Suutari <email>ari@suutari.iki.fi</email></para> - </listitem> - - <listitem> - <para>Brent J. Nordquist <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Bernd Rosauer <email>br@schiele-ct.de</email></para> - </listitem> - - <listitem> - <para>Bill Kish <email>kish@osf.org</email></para> - </listitem> - - <listitem> - <para>&a.wlloyd;</para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Boyd Faulkner <email>faulkner@mpd.tandem.com</email></para> - </listitem> - - <listitem> - <para>Brent J. Nordquist <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Brett Taylor <email>brett@peloton.physics.montana.edu</email></para> - </listitem> - - <listitem> - <para>Brian Clapper <email>bmc@willscreek.com</email></para> - </listitem> - - <listitem> - <para>Brian Handy <email>handy@lambic.space.lockheed.com</email></para> - </listitem> - - <listitem> - <para>Brian Tao <email>taob@risc.org</email></para> - </listitem> - - <listitem> - <para>Brion Moss <email>brion@queeg.com</email></para> - </listitem> - - <listitem> - <para>Bruce Gingery <email>bgingery@gtcs.com</email></para> - </listitem> - - <listitem> - <para>Carey Jones <email>mcj@acquiesce.org</email></para> - </listitem> - - <listitem> - <para>Carl Fongheiser <email>cmf@netins.net</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Charles Mott <email>cmott@srv.net</email></para> - </listitem> - - <listitem> - <para>Chet Ramey <email>chet@odin.INS.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Chris Dabrowski <email>chris@vader.org</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Shenton <email>cshenton@angst.it.hq.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Chris Stenton <email>jacs@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>Chris Timmons <email>skynyrd@opus.cts.cwu.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christian Gusenbauer <email>cg@fimp01.fim.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christian Haury <email>Christian.Haury@sagem.fr</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Choi Jun Ho <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>Chuck Hein <email>chein@cisco.com</email></para> - </listitem> - - <listitem> - <para>Conrad Sabatier <email>conrads@neosoft.com</email></para> - </listitem> - - <listitem> - <para>Cornelis van der Laan <email>nils@guru.ims.uni-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Craig Struble <email>cstruble@vt.edu</email></para> - </listitem> - - <listitem> - <para>Cristian Ferretti <email>cfs@riemann.mat.puc.cl</email></para> - </listitem> - - <listitem> - <para>Curt Mayer <email>curt@toad.com</email></para> - </listitem> - - <listitem> - <para>Dai Ishijima <email>ishijima@tri.pref.osaka.jp</email></para> - </listitem> - - <listitem> - <para>Dan Cross <email>tenser@spitfire.ecsel.psu.edu</email></para> - </listitem> - - <listitem> - <para>Daniel Baker <email>dbaker@crash.ops.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Daniel M. Eischen <email>deischen@iworks.InterWorks.org</email></para> - </listitem> - - <listitem> - <para>Daniel O'Connor <email>doconnor@gsoft.com.au</email></para> - </listitem> - - <listitem> - <para>Danny J. Zerkel <email>dzerkel@feephi.phofarm.com</email></para> - </listitem> - - <listitem> - <para>Dave Bodenstab <email>imdave@synet.net</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Chapeskie <email>dchapes@zeus.leitch.com</email></para> - </listitem> - - <listitem> - <para>Dave Edmondson <email>davided@sco.com</email></para> - </listitem> - - <listitem> - <para>Dave Rivers <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David A. Bader <email>dbader@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Holloway <email>daveh@gwythaint.tamis.com</email></para> - </listitem> - - <listitem> - <para>David Leonard <email>d@scry.dstc.edu.au</email></para> - </listitem> - - <listitem> - <para>Dean Huxley <email>dean@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Dirk Froemberg <email>dirk@hal.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Dmitrij Tejblum <email>dima@tejblum.dnttm.rssi.ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Kohmanyuk <email>dk@farm.org</email></para> - </listitem> - - <listitem> - <para>&a.whiteside;</para> - </listitem> - - <listitem> - <para>Don Yuniskis <email>dgy@rtd.com</email></para> - </listitem> - - <listitem> - <para>Donald Burr <email>d_burr@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Doug Ambrisko <email>ambrisko@ambrisko.roble.com</email></para> - </listitem> - - <listitem> - <para>Douglas Carmichael <email>dcarmich@mcs.com</email></para> - </listitem> - - <listitem> - <para>Eiji-usagi-MATSUmoto <email>usagi@ruby.club.or.jp</email></para> - </listitem> - - <listitem> - <para>ELISA Font Project</para> - </listitem> - - <listitem> - <para>Eric A. Griff <email>eagriff@global2000.net</email></para> - </listitem> - - <listitem> - <para>Eric Blood <email>eblood@cs.unr.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Chet <email>ejc@bazzle.com</email></para> - </listitem> - - <listitem> - <para>Eric J. Schwertfeger <email>eric@cybernut.com</email></para> - </listitem> - - <listitem> - <para>Francis M J Hsieh <email>mjhsieh@life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Bartels <email>knarf@camelot.de</email></para> - </listitem> - - <listitem> - <para>Frank Chen Hsiung Chan <email>frankch@waru.life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Frank Nobis <email>fn@trinity.radio-do.de</email></para> - </listitem> - - <listitem> - <para>FUJIMOTO Kensaku <email>fujimoto@oscar.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>FURUSAWA Kazuhisa <email>furusawa@com.cs.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Kline <email>kline@thought.org</email></para> - </listitem> - - <listitem> - <para>Gerard Roudier <email>groudier@club-internet.fr</email></para> - </listitem> - - <listitem> - <para>Greg Ungerer <email>gerg@stallion.oz.au</email></para> - </listitem> - - <listitem> - <para>Harlan Stenn <email>Harlan.Stenn@pfcs.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Hideaki Ohmon <email>ohmon@tom.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidekazu Kuroki <email>hidekazu@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidetoshi Shimokawa <email>simokawa@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hideyuki Suzuki <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hironori Ikura <email>hikura@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Hung-Chi Chu <email>hcchu@r350.ee.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ian Vaudrey <email>i.vaudrey@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Igor Vinokurov <email>igor@zynaps.ru</email></para> - </listitem> - - <listitem> - <para>Ikuo Nakagawa <email>ikuo@isl.intec.co.jp</email></para> - </listitem> - - <listitem> - <para>IMAMURA Tomoaki <email>tomoak-i@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro</para> - </listitem> - - <listitem> - <para>Issei Suzuki <email>issei@t-cnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Itsuro Saito <email>saito@miv.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>J. David Lowe <email>lowe@saturn5.com</email></para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Janusz Kokot <email>janek@gaja.ipan.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Jason Thorpe <email>thorpej@nas.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Javier Martin Rueda <email>jmrueda@diatel.upm.es</email></para> - </listitem> - - <listitem> - <para>Jeff Bartig <email>jeffb@doit.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Jeffrey Wheat <email>jeff@cetlink.net</email></para> - </listitem> - - <listitem> - <para>Jian-Da Li <email>jdli@csie.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Jim Binkley <email>jrb@cs.pdx.edu</email></para> - </listitem> - - <listitem> - <para>Jim Lowe <email>james@cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Joao Carlos Mendes Luis <email>jonny@coppe.ufrj.br</email></para> - </listitem> - - <listitem> - <para>Joel Sutton <email>sutton@aardvark.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Johann Tonsing <email>jtonsing@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>John Capo <email>jc@irbs.com</email></para> - </listitem> - - <listitem> - <para>John Heidemann <email>johnh@isi.edu</email></para> - </listitem> - - <listitem> - <para>John Perry <email>perry@vishnu.alias.net</email></para> - </listitem> - - <listitem> - <para>John Polstra <email>jdp@polstra.com</email></para> - </listitem> - - <listitem> - <para>John Rochester <email>jr@cs.mun.ca</email></para> - </listitem> - - <listitem> - <para>Josef Karthauser <email>joe@uk.freebsd.org</email></para> - </listitem> - - <listitem> - <para>Joseph Stein <email>joes@seaport.net</email></para> - </listitem> - - <listitem> - <para>Josh Gilliam <email>josh@quick.net</email></para> - </listitem> - - <listitem> - <para>Josh Tiefenbach <email>josh@ican.net</email></para> - </listitem> - - <listitem> - <para>Juergen Lock <email>nox@jelal.hb.north.de</email></para> - </listitem> - - <listitem> - <para>Juha Inkari <email>inkari@cc.hut.fi</email></para> - </listitem> - - <listitem> - <para>Julian Assange <email>proff@suburbia.net</email></para> - </listitem> - - <listitem> - <para>Julian Jenkins <email>kaveman@magna.com.au</email></para> - </listitem> - - <listitem> - <para>Julian Stacey <email>jhs@freebsd.org</email></para> - </listitem> - - <listitem> - <para>Junichi Satoh <email>junichi@jp.freebsd.org</email></para> - </listitem> - - <listitem> - <para>Kapil Chowksey <email>kchowksey@hss.hns.com</email></para> - </listitem> - - <listitem> - <para>Kazuhiko Kiriyama <email>kiri@kiri.toba-cmt.ac.jp</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@bostic.com</email></para> - </listitem> - - <listitem> - <para>Keith Moore</para> - </listitem> - - <listitem> - <para>Kenneth Monville <email>desmo@bandwidth.org</email></para> - </listitem> - - <listitem> - <para>Kent Vander Velden <email>graphix@iastate.edu</email></para> - </listitem> - - <listitem> - <para>Kirk McKusick <email>mckusick@mckusick.com</email></para> - </listitem> - - <listitem> - <para>Kiroh HARADA <email>kiroh@kh.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Koichi Sato <email>copan@ppp.fastnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Kostya Lukin <email>lukin@okbmei.msk.su</email></para> - </listitem> - - <listitem> - <para>Kurt Olsen <email>kurto@tiny.mcs.usu.edu</email></para> - </listitem> - - <listitem> - <para>Lars Koeller <email>Lars.Koeller@Uni-Bielefeld.DE</email></para> - </listitem> - - <listitem> - <para>Lucas James <email>Lucas.James@ldjpc.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Luigi Rizzo <email>luigi@iet.unipi.it</email></para> - </listitem> - - <listitem> - <para>Makoto MATSUSHITA <email>matusita@jp.freebsd.org</email></para> - </listitem> - - <listitem> - <para>Manu Iyengar <email>iyengar@grunthos.pscwa.psca.com</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Marc Ramirez <email>mrami@mramirez.sy.yale.edu</email></para> - </listitem> - - <listitem> - <para>Marc Slemko <email>marcs@znep.com</email></para> - </listitem> - - <listitem> - <para>Marc van Kempen <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>Mario Sergio Fujikawa Ferreira <email>lioux@gns.com.br</email></para> - </listitem> - - <listitem> - <para>Mark Huizer <email>xaa@stack.nl</email></para> - </listitem> - - <listitem> - <para>Mark J. Taylor <email>mtaylor@cybernet.com</email></para> - </listitem> - - <listitem> - <para>Mark Krentel <email>krentel@rice.edu</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email> <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Birgmeier</para> - </listitem> - - <listitem> - <para>Martti Kuparinen <email>erakupa@kk.etx.ericsson.se</email></para> - </listitem> - - <listitem> - <para>Masachika ISHIZUKA <email>ishizuka@isis.min.ntt.jp</email></para> - </listitem> - - <listitem> - <para>Mats Lofkvist <email>mal@algonet.se</email></para> - </listitem> - - <listitem> - <para>Matt Bartley <email>mbartley@lear35.cytex.com</email></para> - </listitem> - - <listitem> - <para>Matt Thomas <email>thomas@lkg.dec.com</email></para> - </listitem> - - <listitem> - <para>Matt White <email>mwhite+@CMU.EDU</email></para> - </listitem> - - <listitem> - <para>Matthew Hunt <email>mph@pobox.com</email></para> - </listitem> - - <listitem> - <para>Matthew N. Dodd <email>winter@jurai.net</email></para> - </listitem> - - <listitem> - <para>Matthew Stein <email>matt@bdd.net</email></para> - </listitem> - - <listitem> - <para>Maurice Castro <email>maurice@planet.serc.rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Michael Butschky <email>butsch@computi.erols.com</email></para> - </listitem> - - <listitem> - <para>Michael Elbel <email>me@FreeBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Michael Searle <email>searle@longacre.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Miguel Angel Sagreras <email>msagre@cactus.fi.uba.ar</email></para> - </listitem> - - <listitem> - <para>Mikael Hybsch <email>micke@dynas.se</email></para> - </listitem> - - <listitem> - <para>Mikhail Teterin <email>mi@aldan.ziplink.net</email></para> - </listitem> - - <listitem> - <para>Mike McGaughey <email>mmcg@cs.monash.edu.au</email></para> - </listitem> - - <listitem> - <para>Mike Peck <email>mike@binghamton.edu</email></para> - </listitem> - - <listitem> - <para>Ming-I Hseh <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>MITA Yoshio <email>mita@jp.FreeBSD.ORG</email></para> - </listitem> - - <listitem> - <para>MOROHOSHI Akihiko <email>moro@race.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Murray Stokely <email>murray@cdrom.com</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Kazushi <email>nkazushi@highway.or.jp</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Narvi <email>narvi@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>NIIMI Satoshi <email>sa2c@and.or.jp</email></para> - </listitem> - - <listitem> - <para>Nick Sayer <email>nsayer@quack.kfu.com</email></para> - </listitem> - - <listitem> - <para>Nicolas Souchu <email>Nicolas.Souchu@prism.uvsq.fr</email></para> - </listitem> - - <listitem> - <para>Nisha Talagala <email>nisha@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Nobuhiro Yasutomi <email>nobu@psrc.isac.co.jp</email></para> - </listitem> - - <listitem> - <para>Nobuyuki Koganemaru <email>kogane@kces.koganemaru.co.jp</email></para> - </listitem> - - <listitem> - <para>Noritaka Ishizumi <email>graphite@jp.FreeBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Oliver Fromme <email>oliver.fromme@heim3.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Oliver Laumann <email>net@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Oliver Oberdorf <email>oly@world.std.com</email></para> - </listitem> - - <listitem> - <para>Paul Fox <email>pgf@foxharp.boston.ma.us</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>paulo@isr.uc.pt</email></para> - </listitem> - - <listitem> - <para>Paul T. Root <email>proot@horton.iaces.com</email></para> - </listitem> - - <listitem> - <para>Pedro Giffuni <email>giffunip@asme.org</email></para> - </listitem> - - <listitem> - <para>Pedro A M Vazquez <email>vazquez@IQM.Unicamp.BR</email></para> - </listitem> - - <listitem> - <para>Peter Cornelius <email>pc@inr.fzk.de</email></para> - </listitem> - - <listitem> - <para>Peter Haight <email>peterh@prognet.com</email></para> - </listitem> - - <listitem> - <para>Peter Hawkins <email>peter@rhiannon.clari.net.au</email></para> - </listitem> - - <listitem> - <para>Peter Stubbs <email>PETERS@staidan.qld.edu.au</email></para> - </listitem> - - <listitem> - <para>Pierre Beyssac <email>bp@fasterix.freenix.org</email></para> - </listitem> - - <listitem> - <para>Phil Maker <email>pjm@cs.ntu.edu.au</email></para> - </listitem> - - <listitem> - <para>R. Kym Horsell</para> - </listitem> - - <listitem> - <para>Randall Hopper <email>rhh@stealth.ct.picker.com</email></para> - </listitem> - - <listitem> - <para>Richard Hwang <email>rhwang@bigpanda.com</email></para> - </listitem> - - <listitem> - <para>Richard Seaman, Jr. <email>dick@tar.com</email></para> - </listitem> - - <listitem> - <para>Richard Stallman <email>rms@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Richard Wiwatowski <email>rjwiwat@adelaide.on.net</email></para> - </listitem> - - <listitem> - <para>Rob Mallory <email>rmallory@csusb.edu</email></para> - </listitem> - - <listitem> - <para>Rob Shady <email>rls@id.net</email></para> - </listitem> - - <listitem> - <para>Rob Snow <email>rsnow@txdirect.net</email></para> - </listitem> - - <listitem> - <para>Robert Sanders <email>rsanders@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Robert Withrow <email>witr@rwwa.com</email></para> - </listitem> - - <listitem> - <para>Ronald Kuehn <email>kuehn@rz.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Roland Jesse <email>jesse@cs.uni-magdeburg.de</email></para> - </listitem> - - <listitem> - <para>Ruslan Shevchenko <email>rssh@cki.ipri.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Samuel Lam <email>skl@ScalableNetwork.com</email></para> - </listitem> - - <listitem> - <para>Sander Vesik <email>sander@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Sandro Sigala <email>ssigala@globalnet.it</email></para> - </listitem> - - <listitem> - <para>Sascha Blank <email>blank@fox.uni-trier.de</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Satoshi Taoka <email>taoka@infonets.hiroshima-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Scott Blachowicz <email>scott.blachowicz@seaslug.org</email></para> - </listitem> - - <listitem> - <para>Scott A. Kenney <email>saken@rmta.ml.org</email></para> - </listitem> - - <listitem> - <para>Serge V. Vakulenko <email>vak@zebub.msk.su</email></para> - </listitem> - - <listitem> - <para>Sheldon Hearn <email>axl@iafrica.com</email></para> - </listitem> - - <listitem> - <para>Simon Marlow <email>simonm@dcs.gla.ac.uk</email></para> - </listitem> - - <listitem> - <para>Slaven Rezic (Tomic) <email>eserte@cs.tu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Soren Dayton <email>csdayton@midway.uchicago.edu</email></para> - </listitem> - - <listitem> - <para>Soren Dossing <email>sauber@netcom.com</email></para> - </listitem> - - <listitem> - <para>Stefan Moeding <email>moeding@bn.DeTeMobil.de</email></para> - </listitem> - - <listitem> - <para>Stephane Legrand <email>stephane@lituus.fr</email></para> - </listitem> - - <listitem> - <para>Stephen J. Roznowski <email>sjr@home.net</email></para> - </listitem> - - <listitem> - <para>Steve Gerakines <email>steve2@genesis.tiac.net</email></para> - </listitem> - - <listitem> - <para>Suzuki Yoshiaki <email>zensyo@ann.tama.kawasaki.jp</email></para> - </listitem> - - <listitem> - <para>Tadashi Kumano <email>kumano@strl.nhk.or.jp</email></para> - </listitem> - - <listitem> - <para>Taguchi Takeshi <email>taguchi@tohoku.iij.ad.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Ariga <email>a00821@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@lambert.org</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tetsuya Furukawa <email>tetsuya@secom-sis.co.jp</email></para> - </listitem> - - <listitem> - <para>Theo Deraadt <email>deraadt@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Thomas König <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para> - </listitem> - - <listitem> - <para>Þórður Ívarsson <email>totii@est.is</email></para> - </listitem> - - <listitem> - <para>Tim Kientzle <email>kientzle@netcom.com</email></para> - </listitem> - - <listitem> - <para>Tim Wilkinson <email>tim@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Tom Samplonius <email>tom@misery.sdf.com</email></para> - </listitem> - - <listitem> - <para>Torbjorn Granlund <email>tege@matematik.su.se</email></para> - </listitem> - - <listitem> - <para>Toshihiro Kanda <email>candy@fct.kgc.co.jp</email></para> - </listitem> - - <listitem> - <para>Trefor S. <email>trefor@flevel.co.uk</email></para> - </listitem> - - <listitem> - <para>Ville Eerola <email>ve@sci.fi</email></para> - </listitem> - - <listitem> - <para>Werner Griessl <email>werner@btp1da.phy.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Wes Santee <email>wsantee@wsantee.oz.net</email></para> - </listitem> - - <listitem> - <para>Wilko Bulte <email>wilko@yedi.iaf.nl</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@kintaro.cologne.de</email></para> - </listitem> - - <listitem> - <para>Wu Ching-hong <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshiro Mihira <email>sanpei@yy.cs.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yukihiro Nakai <email>nakai@mlab.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@cpcoup5.tn.tudelft.nl</email></para> - </listitem> - - </itemizedlist> - - - </sect1> - - <sect1> - <title>386BSD Patch Kit Patch Contributors</title> - - <para>(in alphabetical order by first name):</para> - - - <itemizedlist> - - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>adrian@ibmpcug.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrey A. Chernov <email>ache@astral.msk.su</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew Moore <email>alm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email> <email>jtk@netcom.com</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Branko Lankester</para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Rivers <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Greenman <email>davidg@Root.COM</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Felix Gaehtgens <email>felix@escape.vsse.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Guido van Rooij <email>guido@gvr.win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@auspex.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@novatel.cuc.ab.ca</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro, R. Kym Horsell</para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James W. Dolter</para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jörg Lohse <email>lohse@tech7.informatik.uni-hamburg.de</email></para> - </listitem> - - <listitem> - <para>Jörg Wunsch <email>joerg_wunsch@uriah.heep.sax.de</email></para> - </listitem> - - <listitem> - <para>John Dyson <email>formerly - dyson@ref.tfs.com</email></para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jordan K. Hubbard <email>jkh@whisker.hubbard.ie</email></para> - </listitem> - - <listitem> - <para>Julian Elischer <email>julian@dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Julian Stacey <email>jhs@freebsd.org</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email> <email>karl@one.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@toe.CS.Berkeley.EDU</email></para> - </listitem> - - <listitem> - <para>Ken Hughes</para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml%rokkaku.UUCP@mathcs.emory.edu</email> <email>kml@mosquito.cis.ufl.edu</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email> <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Nate Williams <email>nate@bsd.coe.montana.edu</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email> <email>nick@madhouse.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Peter da Silva <email>peter@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Poul-Henning Kamp<email>phk@FreeBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>root@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Rodney W. Grimes <email>rgrimes@cdrom.com</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan <email>sef@kithrup.com</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email> <email>sjg@zen.void.oz.au</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@icarus.weber.edu</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tor Egge <email>Tor.Egge@idi.ntnu.no</email></para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@dentaro.GUN.de</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - - </itemizedlist> - - - - </sect1> - </chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-shorttag: nil - sgml-always-quote-attributes: t - sgml-minimize-attributes: max - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/articles/fonts/Makefile b/en_US.ISO8859-1/articles/fonts/Makefile deleted file mode 100644 index 260184f87c..0000000000 --- a/en_US.ISO8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= fonts.docb -INDEXLINK= fonts.html - -.include "../../web.mk" diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml deleted file mode 100644 index dd781b6f04..0000000000 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,766 +0,0 @@ -<!-- $Id: article.sgml,v 1.2 1998-06-26 10:47:27 jkoshy Exp $ --> -<!-- The FreeBSD Documentation Project --> -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> - -<!-- Recently, I wanted to figure out how to use some additional fonts that - I had accumulated. I finally figured out *how to do it* from the various - man pages and documentation. Since it might be of use to other users, - and I didn't see any reference to this topic in the FAQ or handbook, I - thought I'd try my hand at a simple cookbook tutorial addressing the - use of fonts. I have included my unanswered questions at the end of - the document. - - Anyway, here's what I put together. This is my present understanding of - fonts and how to use them with FreeBSD. I am sure that there are errors or - misunderstandings, but it contains enough valid information to allow the - use of additional fonts with Ghostscript, X11 and Groff. This is my first - attempt to write anything along the lines of a tutorial/FAQ, so I am sure - it is pretty raw. There are probably better ways to do some of this stuff, - and I would welcome being corrected. - --> - -<book> - -<bookinfo> -<bookbiblio> -<title>Fonts and FreeBSD</title> -<subtitle>A Tutorial</subtitle> - -<authorgroup> -<author> -<firstname>Dave</firstname> -<surname>Bodenstab</surname> -<affiliation> -<address><email>imdave@synet.net</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>Wed Aug 7, 1996</pubdate> - -<abstract><para>This document contains a description of the various -font files that may be used with FreeBSD and the syscons driver, X11, -Ghostscript and Groff. Cookbook examples are provided for switching -the syscons display to 80x60 mode, and for using type 1 fonts with -the above application programs.</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction</title> - -<para>There are many sources of fonts available, and one might ask -how they might be used with FreeBSD. The answer can be found by -carefully searching the documentation for the component that one -would like to use. This is very time consuming, so this tutorial is -an attempt to provide a shortcut for others who might be -interested.</para> - -</chapter> - -<chapter> -<title>Basic terminology</title> - -<para>There are many different font formats and associated font file -suffixes. A few that will be addressed here are: -<variablelist> - -<varlistentry><term><filename>.pfa</>, <filename>.pfb</></term> - -<listitem><para>Postscript type 1 fonts. The <filename>.pfa</filename> is the -<emphasis>A</emphasis>scii form and <filename>.pfb</filename> the -<emphasis>B</emphasis>inary form.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.afm</></term> - -<listitem><para>The font metrics associated with a type 1 -font.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.pfm</></term> - -<listitem><para>The printer font metrics associated with a type 1 -font.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.ttf</></term> - -<listitem><para>A TrueType font</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.fot</></term> - -<listitem><para>An indirect reference to a TrueType font (not an -actual font)</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.fon</>, <filename>.fnt</></term> - -<listitem><para>Bitmapped screen fonts</para></listitem> - -</varlistentry> -</variablelist></para> - -<para>The <filename>.fot</filename> file is used by Windows as sort -of a symbolic link to the actual TrueType font -(<filename>.ttf</filename>) file. The <filename>.fon</filename> font -files are also used by Windows. I know of no way to use this font -format with FreeBSD.</para> - -</chapter> - -<chapter> -<title>What font formats can I use?</title> - -<para>Which font file format is useful depends on the application -being used. FreeBSD by itself uses no fonts. Application programs -and/or drivers may make use of the font files. Here is a small cross -reference of application/driver to the font type suffixes:</para> - -<para> -<variablelist> -<varlistentry><term>Driver</term> -<listitem> -<para> -<variablelist> -<varlistentry><term>syscons</term> -<listitem> -<para><filename>.fnt</></para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Application</term> - -<listitem> -<para> -<variablelist> -<varlistentry><term>Ghostscript</term> -<listitem> -<para><filename>.pfa</filename>, <filename>.pfb</filename>, <filename>.ttf</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>X11</term> - -<listitem> -<para><filename>.pfa</filename>, <filename>.pfb</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>Groff</term> - -<listitem> -<para><filename>.pfa</filename>, <filename>.afm</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>Povray</term> - -<listitem> -<para><filename>.ttf</filename></para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -<para>The <filename>.fnt</filename> suffix is used quite frequently. -I suspect that whenever someone wanted to create a specialized font -file for their application, more often than not they chose this -suffix. Therefore, it is likely that files with this suffix are not -all the same format; specifically, the <filename>.fnt</filename> -files used by syscons under FreeBSD may not be the same format as a -<filename>.fnt</filename> file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -<filename>.fnt</filename> files other than those provided with -FreeBSD.</para> - -</chapter> - -<chapter> -<title>Setting a virtual console to 80x60 line mode</title> - -<para>First, a 8x8 font must be loaded. -<filename>/etc/sysconfig</filename> should contain the lines: -<informalexample> -<programlisting># Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt</programlisting> -</informalexample> -</para> - -<para>The command to actually switch the mode is -<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>: -<informalexample> -<screen>bash$ <userinput>vidcontrol VGA_80x60</userinput></screen> -</informalexample> -</para> - -<para>Various screen orientated programs, such as -<citerefentry><refentrytitle>vi</><manvolnum>1</></>, must be able to -determine the current screen dimensions. These can be set with -<citerefentry><refentrytitle>stty</><manvolnum>1</></>: -<informalexample> -<screen>bash$ <userinput>stty crt rows 60 columns 80</userinput></screen> -</informalexample> -</para> - -<para>To make this more seamless, one can embed these commands in the -startup scripts so it takes place when the system boots. One way to -do this is: -<orderedlist> - -<listitem> -<para>Modify <filename>/etc/sysconfig</filename> as above</para> -</listitem> - -<listitem> -<para>Add to <filename>/etc/rc.local</filename>: -<informalexample> -<programlisting>for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done</programlisting> -</informalexample></para> -</listitem> - -<listitem> -<para>Add to <filename>/etc/profile</filename>: -<informalexample> -<programlisting>TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi</programlisting> -</informalexample> -</para> -</listitem> - -</orderedlist> -</para> - -<para>References: -<citerefentry><refentrytitle>stty</><manvolnum>1</></>, -<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>.</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with X11</title> - -<para>X11 can use either the <filename>.pfa</filename> or the -<filename>.pfb</filename> format fonts. The X11 fonts are located in -various subdirectories under -<filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file is -cross referenced to its X11 name by the contents of the -<filename>fonts.dir</filename> file in each directory.</para> - -<para>There is already a directory named <filename>Type1</>. The most -straight forward way to add a new font is to put it into this -directory. A better way is to keep all new fonts in a separate -directory and use a symbolic link to the additional font. This -allows one to more easily keep track of ones fonts without confusing -them with the fonts that were originally provided. For -example: -<informalexample> -<screen><lineannotation>Create a directory to contain the font files</> -bash$ <userinput>mkdir -p /usr/local/share/fonts/type1</> -bash$ <userinput>cd /usr/local/share/fonts/type1</> - -<lineannotation>Place the .pfa, .pfb and .afm files here</> -<lineannotation>One might want to keep readme files, and other documentation</> -<lineannotation>for the fonts here also</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</> - -<lineannotation>Maintain an index to cross reference the fonts</> -bash$ <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX</></screen> -</informalexample> -</para> - -<para>Now, to use a new font with X11, one must make the font file -available and update the font name files. The X11 font names look -like: -<informalexample> -<screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style</screen> -</informalexample> -</para> - -<para>A new name needs to be created for each new font. If you have -some information from the documentation that accompanied the font, -then it could serve as the basis for creating the name. If there is -no information, then you can get some idea by using -<citerefentry><refentrytitle>strings</><manvolnum>1</></> on the font -file. For example: -<informalexample> -<screen>bash$ <userinput>strings showboat.pfb | more</> -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin--</screen> -</informalexample></para> - -<para>Using this information, a possible name might be: -<informalexample> -<screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1</screen> -</informalexample> -</para> - -<para>The components of our name are: -<variablelist> - -<varlistentry><term>Foundry</term> -<listitem> -<para>Lets just name all the new fonts <literal>type1</>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Family</term> -<listitem> -<para>The name of the font.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Weight</term> -<listitem> -<para>Normal, bold, medium, semibold, etc. From the -<citerefentry><refentrytitle>strings</><manvolnum>1</></> output -above, it appears that this font has a weight of -<emphasis>medium</emphasis>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Slant</term> -<listitem> -<para><emphasis remap=bf>r</emphasis>oman, <emphasis -remap=bf>i</emphasis>talic, <emphasis remap=bf>o</emphasis>blique, -etc. Since the <emphasis>ItalicAngle</emphasis> is zero, -<emphasis>roman</emphasis> will be used.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Width</term> -<listitem> -<para>Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be <emphasis>normal</emphasis>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Additional style</term> -<listitem> -<para>Usually omitted, but this will indicate that -the font contains decorative capital letters.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Spacing</term> -<listitem> -<para>proportional or monospaced. <emphasis>Proportional</emphasis> -is used since <emphasis>isFixedPitch</emphasis> is false.</para> -</listitem> -</varlistentry> - -</variablelist> -</para> - -<para>All of these names are arbitrary, but one should strive to be -compatible with the existing conventions. A font is referenced by -name with possible wild cards by an X11 program, so the name chosen -should make some sense. One might begin by simply using -<informalexample> -<screen>…-normal-r-normal-…-p-…</screen> -</informalexample> -as the name, and then use -<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></> to examine it -and adjust the name based on the appearance of the font.</para> - -<para>So, to complete our example: -<informalexample> -<screen><lineannotation>Make the font accessible to X11</> -bash$ <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line.</> -bash$ <userinput>ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq</> - -<lineannotation><filename>fonts.scale</> seems to be identical to <filename>fonts.dir</>…</> -bash$ <userinput>cp fonts.dir fonts.scale</> - -<lineannotation>Tell X11 that things have changed</> -bash$ <userinput>xset fp rehash</> - -<lineannotation>Examine the new font</> -bash$ <userinput>xfontsel -pattern -type1-*</></screen> -</informalexample> -</para> - -<para>References: -<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></>, -<citerefentry><refentrytitle>xset</><manvolnum>1</></>, -<citetitle>The X Windows System in a Nutshell</>, <ulink -URL="http://www.ora.com/">O'Reilly & Associates</ulink>.</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with Ghostscript</title> - -<para>Ghostscript references a font via its <filename>Fontmap</> -file. This must be modified in a similar way to the X11 -<filename>fonts.dir</filename> file. Ghostscript can use either the -<filename>.pfa</filename> or the <filename>.pfb</filename> format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: -<informalexample> -<screen><lineannotation>Put the font in Ghostscript's font directory</> -bash$ <userinput>cd /usr/local/share/ghostscript/fonts</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit Fontmap so Ghostscript knows about the font</> -bash$ <userinput>cd /usr/local/share/ghostscript/4.01</> -bash$ <userinput>ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq</> - -<lineannotation>Use Ghostscript to examine the font</> -bash$ <userinput>gs prfont.ps</> -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS><userinput>Showboat DoFont</> -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS><userinput>quit</></screen> -</informalexample> -</para> - -<para>References: <filename>fonts.txt</filename> in the Ghostscript -4.01 distribution</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with Groff</title> - -<para>Now that the new font can be used by both X11 and Ghostscript, -how can one use the new font with groff? First of all, since we are -dealing with type 1 postscript fonts, the groff device that is -applicable is the <emphasis>ps</emphasis> device. A font file must be -created for each font that groff can use. A groff font name is just -a file in <filename>/usr/share/groff_font/devps</filename>. With our -example, the font file could be -<filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The file -must be created using tools provided by groff.</para> - -<para>The first tool is <command>afmtodit</>. This is not normally -installed, so it must be retrieved from the source distribution. I -found I had to change the first line of the file, so I did: -<informalexample> -<screen>bash$ <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</> -bash$ <userinput>ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq</></screen> -</informalexample> -</para> - -<para>This tool will create the groff font file from the metrics file -(<filename>.afm</filename> suffix.) Continuing with our -example: -<informalexample> -<screen><lineannotation>Many <filename>.afm</> files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines</> -bash$ <userinput>cd /tmp</> -bash$ <userinput>cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm</> - -<lineannotation>Now create the groff font file</> -bash$ <userinput>cd /usr/share/groff_font/devps</> -bash$ <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</></screen> -</informalexample> -</para> - -<para>The font can now be referenced with the name SHOWBOAT.</para> - -<para>If ghostscript is used to drive the printers on the system, -then nothing more needs to be done. However, if true postscript -printers are used, then the font must be down loaded to the printer -in order for the font to be used (unless the printer happens to have -the showboat font built in or on an accessible font disk.) The final -step is to create a down loadable font. The <command>pfbtops</> tool -is used to create the <filename>.pfa</filename> format of the font, -and the <filename>download</> file is modified to reference the new -font. The <filename>download</> file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: -<informalexample> -<screen><lineannotation>Create the <filename>.pfa</> font file</> -bash$ <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</></screen> -</informalexample> -Of course, if the <filename>.pfa</filename> file is already -available, just use a symbolic link to reference it. -<informalexample> -<screen><lineannotation>Get the internal font name</> -bash$ <userinput>fgrep internalname SHOWBOAT</> -internalname Showboat - -<lineannotation>Tell groff that the font must be down loaded</> -bash$ <userinput>ex download -:$a -Showboat showboat.pfa -. -:wq</></screen> -</informalexample> -</para> - -<para>To test the font: -<informalexample> -<screen>bash$ <userinput>cd /tmp</> -bash$ <userinput>cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF</> -bash$ <userinput>groff -Tps example.t >example.ps</> - -<lineannotation>To use ghostscript/ghostview</> -bash$ <userinput>ghostview example.ps</> - -<lineannotation>To print it</> -bash$ <userinput>lpr -Ppostscript example.ps</></screen> -</informalexample> -</para> - -<para>References: -<filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>, -<citerefentry><refentrytitle>groff_font</><manvolnum>5</></>, -<citerefentry><refentrytitle>groff_char</><manvolnum>5</></>, -<citerefentry><refentrytitle>pfbtops</><manvolnum>1</></>.</para> - -</chapter> - -<chapter> -<title>Can TrueType fonts be used?</title> - -<para>The TrueType font format is used by Windows, Windows 95, and -Mac's. It is quite popular and there are a great number of -fonts available in this format.</para> - -<para>Unfortunately, there are few applications that I am aware of -that can use this format: Ghostscript and Povray come to mind. -Ghostscript's support, according to the documentation, is rudimentary -and the results are likely to be inferior to type 1 fonts. -Povray version 3 also has the ability to use TrueType fonts, but -I rather doubt many people will be creating documents as a series of -raytraced pages :-).</para> - -<para>Using TrueType with groff is difficult because groff would -need a font description file, and I know of no tools to construct -the metrics from a TrueType font. In addition, the font would have to -be downloaded to postscript printers in the appropriate format, -and again, groff cannot handle TrueType fonts in this fashion.</para> - -<para>This rather dismal situation may soon change. -The <ulink url="http://www.freetype.org/">FreeType Project</ulink> -is currently developing a useful set of FreeType tools: -<itemizedlist> -<listitem> -<simpara>The <command>xfsft</command> font server for X11 can serve -TrueType fonts in addition to regular fonts. Though currently in -beta, it is said to be quite useable. See <ulink -url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz -Chroboczek's page</ulink> for further information. Porting instructions -for FreeBSD can be found at <ulink -url="http://math.missouri.edu/~stephen/software/">Stephen Montgomery's -software page</ulink>. -</simpara> -</listitem> -<listitem> -<simpara><command>xfstt</command> is another font -server for X11, available under <ulink -url=" ftp://sunsite.unc.edu/pub/Linux/X11/fonts"> -ftp://sunsite.unc.edu/pub/Linux/X11/fonts</ulink>. -</simpara> -</listitem> -<listitem><simpara>A program called <command>ttf2bdf</command> can produce -BDF files suitable for use in an X environment from TrueType files. Linux -binaries are said to be available from <ulink -url="ftp://crl.nmsu.edu/CLR/multiling/General">ftp://crl.nmsu.edu/CLR/multiling/General/</ulink>. -</simpara> -</listitem> -<listitem> -<simpara> -For people requiring the use of Asian TrueType fonts, the -<command>XTT</command> font server may be worth a look. Information about -<command>XTT</command> can be found at URL: <ulink -url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html">http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html</ulink>. -</simpara> -</listitem> -<listitem> -<simpara>and others …</simpara> -</listitem> -</itemizedlist> -</para> -<para> -The -<ulink url="http://www.freetype.org/projects.htm">FreeType Projects page -</ulink> is a good starting point for information on these and other -free TrueType projects. -</para> -</chapter> - -<chapter> -<title>Where can additional fonts be obtained?</title> - -<para>Many fonts are available on the Internet. They are either -entirely free, or are share-ware. In addition, there are many -inexpensive CDROMs available that contain many fonts. Some Internet -locations (as of August 1996) are: -<itemizedlist> - -<listitem><para><ulink -url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> (Formerly -CICA)</para></listitem> - -<listitem><para><ulink -url="http://www.simtel.net/simcgi-bin/dosfind.cgi">http://www.simtel.net/simcgi-bin/dosfind.cgi</ulink></para></listitem> - -<listitem><para><ulink -url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para></listitem> - -<listitem><para><ulink -url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para></listitem> - -<listitem><para><ulink -url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para></listitem> - -<listitem><para><ulink -url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para></listitem> - -</itemizedlist></para> - -</chapter> - -<chapter> -<title>Additional questions</title> - -<para> -<itemizedlist> - -<listitem> -<para>What use are the <filename>.pfm</filename> files?</para> -</listitem> - -<listitem> -<para>Can one generate the <filename>.afm</filename> file from a <filename>.pfa</filename> or <filename>.pfb</filename>?</para> -</listitem> - -<listitem> -<para>How to generate the groff character mapping files for postscript fonts -with non-standard character names?</para> -</listitem> - -<listitem> -<para>Can xditview and devX?? devices be setup to access all the new fonts?</para> -</listitem> - -<listitem> -<para>It would be good to have examples of using TrueType fonts with povray and -ghostscript.</para> -</listitem> - -</itemizedlist> -</para> - -</chapter> -</book> diff --git a/en_US.ISO8859-1/articles/formatting-media/Makefile b/en_US.ISO8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 158bc4d801..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $ - -DOCS= diskformat.docb -INDEXLINK= diskformat.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index c2cf44f23e..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,464 +0,0 @@ -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<!-- $Id: article.sgml,v 1.5 1998-10-14 03:25:31 dwhite Exp $ --> -<book> - -<bookinfo> -<bookbiblio> -<title>Formatting Media For Use With FreeBSD 2.2-RELEASE</title> -<subtitle>A Tutorial</subtitle> - -<authorgroup> -<author> -<firstname>Doug</firstname> -<surname>White</surname> -<affiliation> -<address><email>dwhite@resnet.uoregon.edu</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>March 1997</pubdate> -<abstract><para>This document describes how to slice, partition, and -format hard disk drives and similar media for use with FreeBSD. The -examples given have been tested under FreeBSD 2.2-GAMMA and may work -for other releases. </para> -</abstract> -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction & Definitions</title> - -<sect1> -<title>Overview</title> -<para>Successfully adding disks to an existing system is the mark of an -experienced system administrator. Slicing, partitioning, and adding -disks requires a careful dance of proper command and name syntax. One -slipped finger and an entire disk could disappear in seconds. This -document is written in an attempt to simplify this process and avoid -accidents. Thankfully, enhancements to existing tools (notably -sysinstall) have greatly improved this process in recent releases of -FreeBSD. </para> - -<para>There are two possible modes of disk formatting: -<itemizedlist> - -<listitem><para><firstterm>compatibility mode</firstterm>: Arranging a -disk so that it has a slice table for use with other operating -systems.</para> </listitem> - -<listitem><para><firstterm>dangerously dedicated mode</firstterm>: -Formatting a disk with no slice table. This makes the process of -adding disks easier, however non-FreeBSD operating systems may not -accept the disk. </para> </listitem> -</itemizedlist> -</para> - -<para>For most cases, dedicated mode is the easiest to set up and use -in existing systems, as a new disk is usually dedicated entirely to -FreeBSD. However, compatibility mode insures optimum interoperability -with future installations at a cost of increased complexity.</para> - -<para>In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -<command>/stand/sysinstall</command>. 2.1.7-RELEASE and later -versions of <command>sysinstall</command> contain code to ease setup -of disks during normal system operation, mainly allowing access to the -Label and Partition editors and a Write feature which will update just -the selected disk and slice without affecting other disks. The other -method is running the tools manually from a root command line. For -dangerously dedicated mode, only three or four commands are involved -while <command>sysinstall</command> requires some manipulation.</para> -</sect1> -<sect1> -<title>Definitions</title> - -<para>UNIX disk management over the centuries has invented many new -definitions for old words. The following glossary covers the -definitions used in this document and (hopefully) for FreeBSD in -general. </para> - -<!-- I'm tempted to use GLOSSARY here but will resort to a list for -now. --> - -<itemizedlist> -<listitem><para>compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode.</para></listitem> - -<listitem><para>dangerously dedicated mode: Formatting a disk with no slice -table. This makes the process of adding disks easier, however -non-FreeBSD operating systems may not accept the disk. Oppose -compatibility mode.</para></listitem> - -<listitem><para>disk: A circular disc, covered with magnetic or similarly -manipulable material, spun by a motor under a head. Data is stored on -the disk by changing the pattern of magnetism on the disc, which can -be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz -removables are examples of disks.</para></listitem> - -<listitem><para>slice: A division of a disk. Up to four slices are permitted on one -disk in the PC standard. Slices are composed of contiguous sectors. -Slices are recorded in a <quote>slice table</quote> used by the system BIOS to -locate bootable partitions. The slice table is usually called the -Partition Table in DOS parlance. Maintained by the fdisk utility.</para></listitem> - -<listitem><para>partition: A division of a slice. Usually used in reference -to divisions of the FreeBSD slice of a disk. Each filesystem and swap -area on a disk resides in a partition. Maintained using the disklabel -utility.</para></listitem> - -<listitem><para>sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data.</para></listitem> - -</itemizedlist> -</sect1> - -<sect1> -<title>Warnings & Pitfalls</title> - -<para>Building disks is not something to take lightly. It is quite possible -to destroy the contents of other disks in your system if the proper -precautions are not taken.</para> - -<para><emphasis>Check your work carefully.</> It is very simple to destroy -the incorrect disk when working with these commands. When -in doubt consult the kernel boot output for the proper device.</para> - -<para>Needless to say, we are not responsible for any damage to any data -or hardware that you may experience. You work at your own risk!</para> - -</sect1> - -<sect1> -<title>Zip, Jaz, and Other Removables</title> - -<para>Removable disks can be formatted in the same way as normal hard -disks. It is essential to have the disk drive connected to the system -and a disk placed in the drive during startup, so the kernel can -determine the drive's geometry. Check the <command>dmesg</command> -output and make sure your device and the disk's size is listed. If -the kernel reports -<informalexample> -<screen> -Can't get the size -</screen> -</informalexample> -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. -</para> -</sect1> - -</chapter> -<chapter> -<title>Formatting Disks in Dedicated Mode</title> - -<sect1> -<title>Introduction</title> - -<para>This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture.</para> - -</sect1> -<sect1> -<title>Making Dedicated Mode Disks using Sysinstall</title> - -<para><command>/stand/sysinstall</command>, the system installation -utility, has been expanded in recent versions to make the process of -dividing disks properly a less tiring affair. The fdisk and disklabel -editors built into sysinstall are GUI tools that remove much of the -confusion from slicing disks. For FreeBSD versions 2.1.7 and later, -this is perhaps the simplest way to slice disks.</para> - -<orderedlist> -<listitem><para>Start sysinstall as root by typing -<informalexample> -<screen><userinput>/stand/sysinstall</userinput></screen> -</informalexample> -from the command prompt.</para></listitem> - -<listitem><para>Select <command>Index</command>.</para></listitem> -<listitem><para>Select <command>Partition</command>.</para></listitem> -<listitem><para>Select the disk to edit with arrow keys and -<keycap>SPACE</keycap>.</para> -</listitem> -<listitem><para>If you are using this entire disk for FreeBSD, select -<command>A</command>.</para></listitem> -<listitem><para>When asked: -<informalexample> -<screen> -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? -</screen> -</informalexample>answer <command>No</command>.</para></listitem> -<listitem><para>When asked if you still want to do this, answer -<command>Yes</command>.</para></listitem> -<listitem><para>Select <command>Write</command>.</para></listitem> -<listitem><para>When warned about Writing on installed systems, answer -<command>Yes</command>.</para></listitem> -<listitem><para><command>Quit</command>the FDISK Editor and -<keycap>ESCAPE</keycap> back to the Index menu.</para></listitem> -<listitem><para>Select <command>Label</command> from the Index -menu.</para></listitem> -<listitem><para>Label as desired. For a single partition, enter -<command>C</command> to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used).</para></listitem> -<listitem><para>Enter <command>W</command> when done and confirm to -continue. The filesystem will be newfs'd for you, unless you select -otherwise (for news partitions you'll want to do this!). You'll get -the error: -<informalexample> -<screen>Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen> -</informalexample> -Ignore. -</para></listitem> -<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem> -</orderedlist> - -</sect1> -<sect1> -<title>Making Dedicated Mode Disks Using the Command Line</title> - - -<para>Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. </para> -<informalexample> -<screen> -<userinput> - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin - # We only want one partition, so using slice 'c' should be fine: - newfs /dev/rwd2c -</userinput> -</screen> -</informalexample> - -<para> If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: </para> - -<informalexample> -<screen> -<userinput> - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/r$d > /tmp/label - # Edit disklabel to add partitions: - vi /tmp/label - disklabel -B -R -r wd2 /tmp/label - # newfs partitions appropriately -</userinput> -</screen> -</informalexample> - -<para>Your disk is now ready for use.</para> - -</sect1> -</chapter> - -<chapter> -<title>Making Compatibility Mode Disks</title> - -<sect1> -<title>Introduction</title> -<para>The command line is the easiest way to make dedicated disks, and -the worst way to make compatibility disks. The command-line fdisk -utility requires higher math skills and an in-depth understanding of -the slice table, which is more than most people want to deal with. -Use sysinstall for compatibility disks, as described below.</para> - -</sect1> -<sect1> - -<title>Making Compatibility Mode Disks Using Sysinstall</title> - -<orderedlist> -<listitem><para>Start sysinstall as root by typing -<informalexample> -<screen><userinput>/stand/sysinstall</></screen> -</informalexample> -from the command prompt.</para></listitem> - -<listitem><para>Select <command>Index</command>.</para> </listitem> -<listitem><para>Select <command>Partition</command>.</para></listitem> -<listitem><para>Select the disk to edit with arrow keys and -<keycap>SPACE</keycap>. -</para></listitem> -<listitem><para>If you are using this entire disk for FreeBSD, select -<command>A</command>.</para></listitem> - -<listitem><para>When asked: -<informalexample> -<screen> -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? -</screen> -</informalexample> answer <command>yes</command>.</para></listitem> -<listitem><para>Select <command>Write</command>.</para></listitem> -<listitem><para>When asked to install the boot manager, select None with -<keycap>SPACE</keycap> then hit <keycap>ENTER</keycap> for OK.</para></listitem> -<listitem><para><command>Quit</command> the FDISK Editor.</para></listitem> -<listitem><para>You'll be asked about the boot manager, select -<command>None</command> -again. </para></listitem> -<listitem><para>Select <command>Label</command> from the Index -menu.</para></listitem> -<listitem><para>Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used).</para></listitem> -<listitem><para>The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error: -<informalexample> -<screen> -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen> -</informalexample> -Ignore. -</para></listitem> -<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem> -</orderedlist> - -<para>Your new disk is now ready for use.</para> - -</sect1> -</chapter> - -<chapter> -<title>Other Disk Operations</title> -<sect1> -<title>Adding Swap Space</title> - -<para>As a system grows, it's need for swap space can also grow. -Although adding swap space to existing disks is very difficult, a new -disk can be partitioned with additional swap space. </para> - -<para>To add swap space when adding a disk to a system: -<orderedlist> -<listitem><para>When partitioning the disk, edit the disklabel and -allocate the amount of swap space to add in partition `b' and the -remainder in another partition, such as `a' or `e'. The size is given -in 512 byte blocks. </para></listitem> -<listitem><para>When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies.</para></listitem> -<listitem><para>Add an entry to <filename>/etc/fstab</filename> as follows: -<informalexample> -<programlisting> -/dev/wd0b none swap sw 0 0 -</programlisting> -</informalexample> -Change /dev/wd0b to the device of the newly added -space.</para></listitem> -<listitem><para>To make the new space immediately available, use the -<command>swapon</command> command. -<informalexample> -<screen> -<userinput> -$ swapon /dev/sd0b -</userinput> -swapon: added /dev/sd0b as swap space -</screen> -</informalexample> -</para></listitem> -</orderedlist> -</para> -</sect1> - -<sect1> -<title>Copying the Contents of Disks</title> -<!-- Should have specific tag --> -<para>Submitted By: Renaud Waldura (<email>renaud@softway.com</email>) </para> - -<para>To move file from your original base disk to the fresh new one, -do: -<informalexample> -<screen> -<userinput> -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home -</userinput> -</screen> -</informalexample> -</para> -</sect1> - -<sect1> -<title>Creating Striped Disks using CCD</title> -<para>Commands Submitted By: Stan Brown (<email>stanb@awod.com</email>) </para> - -<para> -The Concatenated Disk Driver, or CCD, allows you to treat several identical disks as a single disk. -Striping can result in increased disk performance by distributing reads and -writes across the disks. See the ccd(4) and ccdconfig(4) man pages or the -<ulink URL="http://stampede.cs.berkeley.edu/ccd/">CCD Homepage</ulink> for further details.</para> - -<para>To create a new CCD, execute the following commands. This describes -how to add three disks together; simply add or remove devices as -necessary. Remember that the disks to be striped must be <emphasis>identical.</></para> - -<para>Before executing these commands, make sure you add the line -<userinput> -pseudo-device ccd 4 -</userinput> - -to your kernel.</para> - -<informalexample> -<screen> -<userinput> -cd /dev ; sh MAKDEV ccd0 - -disklabel -r -w sd0 auto -disklabel -r -w sd1 auto -disklabel -r -w sd2 auto - -disklabel -e sd0c # change type to 4.2BSD -disklabel -e sd1c # change type to 4.2BSD -disklabel -e sd2c # change type to 4.2BSD - -ccdconfig ccd0 32 0 /dev/sd0c /dev/sd1c /dev/sd2c - -newfs /dev/rccd0c -</userinput> -</screen> -</informalexample> - -<para>Now you can mount and use your CCD by referencing device /dev/ccd0c. -</para> - -</sect1> -</chapter> - -<chapter> -<title>Credits</title> - - - -<para>The author would like to thank the following individuals for -their contributions to this project: -<itemizedlist> -<listitem><para>Darryl Okahata -(<email>darrylo@hpnmhjw.sr.hp.com</email>) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions.</para></listitem> -<listitem><para>Jordan Hubbard -(<email>jkh@freebsd.org</email>) for making -sysinstall useful for this type of task.</para></listitem> -<listitem><para>John Fieber -(<email>jfieber@indiana.edu</email>) for making -information and examples of the DocBook DTD on which this document is -based.</para></listitem> -<listitem><para>Greg Lehey (<email>grog@freebsd.org</email>) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. -</para></listitem> -</itemizedlist> -</para> - -</chapter> - - - -</book> diff --git a/en_US.ISO8859-1/articles/mh/Makefile b/en_US.ISO8859-1/articles/mh/Makefile deleted file mode 100644 index 14a686e6af..0000000000 --- a/en_US.ISO8859-1/articles/mh/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= mh.docb -INDEXLINK= mh.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml deleted file mode 100644 index 3c33cf92ea..0000000000 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,704 +0,0 @@ -<!-- $Id: article.sgml,v 1.2 1997-07-01 21:38:44 max Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>An MH Primer</title> - -<authorgroup> -<author> -<firstname>Matt</firstname> -<surname>Midboe</surname> -<affiliation> -<address> -<email>matt@garply.com</email> -</address> -</affiliation> -</author></authorgroup> - -<pubdate>v1.0, 16 January 1996</pubdate> - -<abstract><para>This document contains an introduction to using MH on -FreeBSD</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter id="mhintro"> -<title>Introduction</title> - -<para>MH started back in 1977 at the RAND Corporation, where the -initial philosophies behind MH were developed. MH isn't so much a -monolithic email program but a philosophy about how best to develop -tools for reading email. The MH developers have done a great job -adhering to the <acronym>KISS</> principle: Keep It Simple Stupid. -Rather than have one large program for reading, sending and handling -email they have written specialized programs for each part of your -email life. One might liken MH to the specialization that one finds -in insects and nature. Each tool in MH does one thing, and does it -very well.</para> - -<para>Beyond just the various tools that one uses to handle their -email MH has done an excellent job keeping the configuration of each -of these tools consistent and uniform. In fact, if you are not quite -sure how something is supposed to work or what the arguments for some -command are supposed to be then you can generally guess and be right. -Each MH command is consistent about how it handles reading the -configuration files and how it takes arguments on the command line. -One useful thing to remember is that you can always add a -<option>-help</option> to the command to have it display the options -for that command.</para> - -<para>The first thing that you need to do is to make sure that you have -installed the MH package on your FreeBSD machine. If you installed -from CDROM you should be able to execute the following to load mh: -<informalexample> -<screen># <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</></screen> -</informalexample> -You will notice that it created a <filename>/usr/local/lib/mh</> -directory for you as well as adding several binaries to the -<filename>/usr/local/bin</> directory. If you would prefer to compile -it yourself then you can anonymous ftp it from <ulink -URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink -URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> - -<para>This primer is not a full comprehensive explanation of how MH -works. This is just intended to get you started on the road to -happier, faster mail reading. You should read the man pages for the -various commands. Also you might want to read the <ulink -URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you can -read the <ulink -URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ -for MH</ulink>. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek.</para> - -</chapter> - -<chapter> -<title>Reading Mail</title> - -<para>This section covers how to use <command>inc</>, -<command>show</>, <command>scan</>, <command>next</>, -<command>prev</>, <command>rmm</>, <command>rmf</>, and -<command>msgchk</>. One of the best things about MH is the -consistent interface between programs. A few things to keep in mind -when using these commands is how to specify message lists. In the -case of <command>inc</> this doesn't really make any sense but with -commands like <command>show</> it is useful to know. </para> - -<para>A message list can consist of something like <parameter>23 20 -16</> which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like <parameter>23-30</> which will -act on all the messages between 23 and 30. You can also specify -something like <parameter>cur:10</> which will act on the current -message and the next 9 messages. The <parameter>cur</>, -<parameter>last</>, and <parameter>first</> messages are special -messages that refer to the current, last or first message in the -folder.</para> - - -<sect1 id="inc"> -<title><command>inc</>, <command>msgchk</>—read in your new email or check it</title> - -<para>If you just type in <userinput>inc</> and hit <keycap>return</> -you will be well on your way to getting started with MH. The first -time you run <command>inc</> it will setup your account to use all -the MH defaults and ask you about creating a Mail directory. If you -have mail waiting to be downloaded you will see something that looks -like: -<informalexample> -<screen> 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> -</informalexample> -This is the same thing you will see from a <command>scan</> (see -<xref linkend="scan">). If you just run <command>inc</> with no -arguments it will look on your computer for email that is supposed to -be coming to you.</para> - -<para>A lot of people like to use POP for grabbing their email. MH can do -POP to grab your email. You will need to give <command>inc</> a few command -line arguments. -<informalexample> -<screen>tempest% <userinput>inc -host mail.pop.org -user <replaceable>username</> -norpop</></screen> -</informalexample> -That tells <command>inc</> to go to <parameter>mail.pop.org</> to -download your email, and that your username on their system is -<replaceable>username</>. The <option>-norpop</option> option tells -<command>inc</> to use plain POP3 for downloading your email. MH has -support for a few different dialects of POP. More than likely you -will never ever need to use them though. While you can do more -complex things with inc such as audit files and scan format files -this will get you going.</para> - -<para>The <command>msgchk</> command is used to get information on -whether or not you have new email. <command>msgchk</> takes the same -<option>-host</option> and <option>-user</option> options that -<command>inc</> takes.</para> - -</sect1> - -<sect1 id="show"> -<title><command>show</>, <command>next</> and <command>prev</>—displaying and moving through email</title> - -<para><command>show</> is to show a letter in your current folder. -Like <command>inc</>, <command>show</> is a fairly straightforward -command. If you just type <userinput>show</> and hit <keycap>return</> -then it displays the current message. You can also give specific -message numbers to show: -<informalexample> -<screen>tempest% <userinput>show 32 45 56</></screen> -</informalexample> -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior <command>show</> -basically just does a <command>more</> on the email message.</para> - -<para><command>next</> is used to move onto the next message and -<command>prev</> will go to the previous message. Both commands have -an implied <command>show</> command so that when you go to the next -message it automatically displays it.</para> - -</sect1> - -<sect1 id="scan"> -<title><command>scan</>—shows you a scan of your messages</title> - -<para><command>scan</> will display a brief listing of the messages -in your current folder. This is an example of what the -<command>scan</> command will give you. -<informalexample> -<screen> 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> -</informalexample> -Like just about everything in MH this display is very configurable. -This is the typical default display. It gives you the message number, -the date on the email, the sender, the subject line, and a sentence -fragment from the very beginning of the email if it can fit it. The -<literal>+</> means that message is the current message, so if you do -a <command>show</> it will display that message.</para> - -<para>One useful option for scan is the <option>-reverse</option> -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -<command>scan</> is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to <command>inc</> it -you can do <command>scan -file -/var/mail/<replaceable>username</></command>. This can be used with -any file that is in the <database>mbox</> format.</para> - -</sect1> - -<sect1 id="rmm"> -<title><command>rmm</> and <command>rmf</>—remove the current message or folder</title> - -<para><command>rmm</> is used to remove a mail message. The default -is typically to not actually remove the message but to rename the -file to one that is ignored by the MH commands. You will need to -through periodically and physically delete the <quote>removed</> -messages.</para> - -<para>The <command>rmf</> command is used to remove folders. This -doesn't just rename the files but actually removes the from the hard -drive so you should be careful when you use this command.</para> - -</sect1> - -<sect1 id="samplereading"> -<title>A typical session of reading with MH</title> - -<para>The first thing that you will want to do is <command>inc</> -your new mail. So at a shell prompt just type in <command>inc</> and -hit <keycap>return</>. -<informalexample> -<screen>tempest% <userinput>inc</> -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest%</screen> -</informalexample> -This shows you the new email that has been added to your mailbox. So -the next thing to do is <command>show</> the email and move around. -<informalexample> -<screen>tempest% <userinput>show</> -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -tempest% <userinput>rmm</> -tempest% <userinput>next</> -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party).</screen> -</informalexample></para> - -<para>The <command>rmm</> removed the current message and the -<command>next</> command moved me on to the next message. -Now if I wanted to look at ten most recent messages so I could read -one of them here is what I would do: -<informalexample> -<screen>tempest% <userinput>scan last:10</> - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest%</screen> -</informalexample> -Then if I wanted to read message number 27 I would do a -<userinput>show 27</> and it would be displayed. As you can probably -tell from this sample session MH is pretty easy to use and looking -through emails and displaying them is fairly intuitive and easy. -</para> - -</sect1> -</chapter> - -<chapter> -<title>Folders and Mail Searching</title> - -<para>Anybody who gets lots of email definitely wants to be able to -prioritize, stamp, brief, de-brief, and number their emails in a -variety of different ways. MH can do this better than just about -anything. One thing that we haven't really talked about is the -concept of folders. You have undoubtedly come across the folders -concept using other email programs. MH has folders too. MH can even -do sub-folders of a folder. One thing you should keep in mind with MH -is that when you ran <command>inc</> for the first time and it asked -you if it could create a <filename>Mail</> directory it began storing -everything in that directory. If you look at that directory you will -find a directory named <filename>inbox</>. The <filename>inbox</> -directory houses all of your incoming mail that hasn't been thrown -anywhere else.</para> - -<para>Whenever you create a new folder a new directory is going to be -created underneath your MH <filename>Mail</> directory, and messages -in that folder are going to be stored in that directory. When new -email comes in that new email is thrown into your <filename>inbox</> -directory with a file name that is equivalent to the message number. -So even if you didn't have any of the MH tools to read your email you -could still use standard UNIX commands to munge around in those -directories and just more your files. It's this simplicity that -really gives you a lot of power with what you can do with your -email.</para> - -<para>Just as you can use message lists like <parameter>23 16 42</> -with most MH commands there is a folder option you can specify with -just about every MH command. If you do a <command>scan +freebsd</> it -will scan your <filename>freebsd</> folder, and your current folder -will be changed to <filename>freebsd</>. If you do a <command>show -+freebsd 23 16 42</>, <command>show</> is going to switch to your -<filename>freebsd</> folder and display messages 23, 16 and 42. So -remember that <option>+<replaceable>folder</></> syntax. You will -need to make sure you use it to make commands process different -folders. Remember you default folder for mail is <filename>inbox</> -so doing a <command>folder +inbox</> should always get you back to -your mail. Of course, in MH's infinite flexibility this can be -changed but most places have probably left it as -<command>inbox</>.</para> - - -<sect1> -<title><command>pick</>—search email that matches certain criteria</title> - -<para><command>pick</> is one of the more complex commands in the MH -system. So you might want to read the -<citerefentry><refentrytitle>pick</><manvolnum>1</></> man page for a -more thorough understanding. At its simplest level you can do -something like -<informalexample> -<screen>tempest% <userinput>pick -search pci</> -15 -42 -55 -56 -57</screen> -</informalexample> - -This will tell <command>pick</> to look through every single line in -every message in your current folder and tell you which message -numbers it found the word <literal>pci</> in. You can then -<command>show</> those messages and read them if you wish or -<command>rmm</> them. You would have to specify something like -<command>show 15 42 55-57</> to display them though. A slightly more -useful thing to do is this: -<informalexample> -<screen>tempest% <userinput>pick -search pci -seq pick</> -5 hits -tempest% <userinput>show pick</></screen> -</informalexample> -This will show you the same messages you just didn't have to work as -hard to do it. The <option>-seq</option> option is really an -abbreviation of <option>-sequence</option> and <command>pick</> is -just a sequence which contains the message numbers that matched. You -can use sequences with just about any MH command. So you could have -done an <command>rmm pick</> and all those messages would be removed -instead. You sequence can be named anything. If you run pick again it -will overwrite the old sequence if you use the same name.</para> - -<para>Doing a <command>pick -search</command> can be a bit more time -consuming than just searching for message from someone, or to -someone. So <command>pick</> allows you to use the following -predefined search criteria: - -<variablelist> - -<varlistentry> -<term><option>-to</option></term> -<listitem> -<para>search based upon who the message is to</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-cc</option></term> -<listitem> -<para>search based on who is in the cc list</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-from</option></term> -<listitem> -<para>search for who sent the message</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-subject</option></term> -<listitem> -<para>search for emails with this subject</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-date</option></term> -<listitem> -<para>find emails with a matching dat</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>--<replaceable>component</replaceable></option></term> -<listitem> -<para>search for any other component in the header. (i.e. -<option>--reply-to</> to find all emails with a certain reply-to in -the header)</para> -</listitem> -</varlistentry> - -</variablelist></para> - -<para>This allows you to do things like -<informalexample> -<screen>tempest% <userinput>pick -to freebsd-hackers@freebsd.org -seq hackers</></screen> -</informalexample> -to get a list of all the email send to the FreeBSD hackers mailing -list. <command>pick</> also allows you to group these criteria in -different ways using the following options: -<itemizedlist> - -<listitem> -<para>… <option>-and</option> …</para> -</listitem> - -<listitem> -<para>… <option>-or</option> &hellip</para> -</listitem> - -<listitem> -<para><option>-not</option> …</para> -</listitem> - -<listitem> -<para><option>-lbrace</option> … <option>-rbrace</option></para> -</listitem> - -</itemizedlist> -These commands allow you to do things like -<informalexample> -<screen>tempest% <userinput>pick -to freebsd-hackers -and -cc freebsd-hackers</></screen> -</informalexample> -That will grab all the email in your inbox that was sent to -freebsd-hackers or cc'd to that list. The brace options allow you to -group search criteria together. This is sometimes very necessary as -in the following example -<informalexample> -<screen>tempest% <userinput>pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci</></screen> -</informalexample></para> - -<para>Basically this says <quote>pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci</quote>. It should look through your -folder and find all messages sent to the freebsd-hackers list that -aren't cc'd to the freebsd-questions list that contain something on -pci in the subject line. Ordinarily you might have to worry about -something called operator precedence. Remember in math how you -evaluate from left to right and you do multiplication and division -first and addition and subtraction second? MH has the same type of -rules for <command>pick</>. It's fairly complex so you might want to study -the man page. This document is just to help you get acquainted with -MH.</para> - -</sect1> - -<sect1> -<title><command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance</title> - -<para>There are three programs which are primarily just for -manipulating your folders. The <command>folder</> program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a <command>folder +<replaceable>newfolder</></> and -you will be switched into <replaceable>newfolder</>. From there on -out all your MH commands like <command>comp</>, <command>repl</>, -<command>scan</>, and <command>show</> will act on that -<command>newfolder</> folder.</para> - -<para>Sometimes when you are reading and deleting messages you will -develop <quote>holes</> in your folders. If you do a <command>scan</> -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a <command>folder -pack</command> this will renumber all your -messages so that there are no holes. It doesn't actually delete any -messages though. So you may need to periodically go through and -physically delete <command>rmm</>'d messages.</para> - -<para>If you need statistics on your folders you can do a -<command>folders</> or <command>folder -all</command> to list all -your folders, how many messages they have, what the current message -is in each one and so on. This line of stats it displays for all your -folders is the same one you get when you change to a folder with -<command>folder +foldername</>. A <command>folders</> command looks -like this: -<informalexample> -<screen> Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. -</screen> -</informalexample></para> - -<para>The <command>refile</> command is what you use to move messages -between folders. When you do something like <command>refile 23 -+netfuture</> message number 23 is moved into the -<filename>netfuture</> folder. You could also do something like -<command>refile 23 +netfuture/latest</> which would put message -number 23 in a subfolder called <filename>latest</> under the -<filename>netfuture</> folder. If you want to keep a message in the -current folder and link it you can do a <command>refile -link 23 -+netfuture</command> which would keep 23 in your current -<filename>inbox</> but also list in your <filename>netfuture</> -folder. You are probably beginning to realize some of the really -powerful things you can do with MH.</para> - -</sect1> -</chapter> - -<chapter> -<title>Sending Mail</title> - -<para>Email is a two way street for most people so you want to be -able to send something back. The way MH handles sending mail can be a -bit difficult to follow at first, but it allows for incredible -flexibility. The first thing MH does is to copy a components file -into your outgoing email. A components file is basically a skeleton -email letter with stuff like the To: and Subject: headers already in -it. You are then sent into your editor where you fill in the header -information and then type the body of your message below the dashed -lines in the message. Then to the <command>whatnow</> program. When -you are at the <prompt>What now?</prompt> prompt you can tell it to -<command>send</>, <command>list</>, <command>edit</>, -<command>edit</>, <command>push</>, and <command>quit</>. Most of -these commands are self-explanatory. So the message sending process -involves copying a component file, editing your email, and then -telling the <command>whatnow</> program what to do with your -email.</para> - - -<sect1> -<title><command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone</title> - -<para>The <command>comp</> program has a few useful command line -options. The most important one to know right now is the -<option>-editor</option> option. When MH is installed the default -editor is usually a program called <command>prompter</> which comes -with MH. It's not a very exciting editor and basically just gets the -job done. So when you go to compose a message to someone you might -want to use <command>comp -editor /usr/bin/vi/</> or <command>comp --editor /usr/local/bin/pico/</> instead. Once you have run -<emphasis>comp</emphasis> you are in your editor and you see -something that looks like this: -<informalexample> -<screen>To: -cc: -Subject: --------- -</screen> -</informalexample></para> - -<para>You need to put the person you are sending the mail to after the -<literal>To:</> line. It works the same way for the other headers -also, so you would need to put your subject after the -<literal>Subject:</> line. Then you would just put the body of your -message after the dashed lines. It may seem a bit simplistic since a -lot of email programs have special requesters that ask you for this -information but there really isn't any point to that. Plus this -really gives you excellent flexibility. -<informalexample> -<screen>To:<userinput>freebsd-rave@freebsd.org</> -cc: -Subject:<userinput>And on the 8th day God created the FreeBSD core team</> --------- -<userinput>Wow this is an amazing operating system. Thanks!</></screen> -</informalexample> -You can now save this message and exit your editor. You will see the -<prompt>What now?</> prompt and you can type in -<userinput>send</> or <userinput>s</> and hit -<keycap>return</>. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example <command>quit</> if you don't want to send the -message.</para> - -<para>The <command>forw</> command is stunningly similar. The big -difference being that the message you are forwarding is automatically -included in the outgoing message. When you run <command>forw</> it -will forward your current message. You can always tell it to forward -something else by doing something like <command>forw 23</> and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences <command>forw</> -functions exactly the same as <command>comp</>. You go through the -exact same message sending process.</para> - -<para>The <command>repl</> command will reply to whatever your -current message is, unless you give it a different message to reply -to. <command>repl</> will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -<literal>To:</> header already has the address of the recipient in -there. Also the <literal>Subject:</> line will already be filled in. -You then go about the normal message composition process and you are -done. One useful command line option to know here is the -<option>-cc</option> option. You can use <parameter>all</>, -<parameter>to</>, <parameter>cc</>, <parameter>me</> after the -<option>-cc</option> option to have <command>repl</> automatically -add the various addresses to the cc list in the message. You have -probably noticed that the original message isn't included. This is -because most MH setups are configured to do this from the -start.</para> - -</sect1> - -<sect1> -<title><filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</></title> - -<para>The <filename>components</> file is usually in -<filename>/usr/local/lib/mh</filename>. You can copy that file into -your MH Mail directory and edit to contain what you want it to -contain. It is a fairly basic file. You have various email headers at -the top, a dashed line and then nothing. The -<command>comp</command> command just copies this -<filename>components</> file and then edits it. You can add any -kind of valid RFC822 header you want. For instance you could have -something like this in your <filename>components</> file: -<informalexample> -<screen>To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ --------</screen> -</informalexample> - -MH would then copy this components file and throw you into your -editor. The <filename>components</> file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that <filename>components</> file.</para> - -<para>The <filename>replcomps</> file is a bit more complex. The default -<filename>replcomps</> looks like this: -<informalexample> -<screen>%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- -</screen> -</informalexample></para> - -<para>It's in the same basic format as the <filename>components</> file but -it contains quite a few extra formatting codes. The -<literal>%(lit)</> command makes room for the address. The -<literal>%(formataddr</> is a function that returns a proper email -address. The next part is <literal>%<</literal> which means if and -the <literal>{reply-to}</> means the reply-to field in the original -message. So that might be translated this way: -<informalexample> -<screen>%<<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> -then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the -from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %? -<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original -message</emphasis>, %> <emphasis remap=bf>endif</emphasis>.</screen> -</informalexample></para> - -<para>As you can tell MH formatting can get rather involved. You can -probably decipher what most of the other functions and variables -mean. All of the information on writing these format strings is in the -MH-Format man page. The really nice thing is that once you have built -your customized <filename>replcomps</> file you won't need to touch it -again. No other email program really gives you the power and -flexibility that MH gives you.</para> - -</sect1> -</chapter> -</book> diff --git a/en_US.ISO8859-1/articles/multi-os/Makefile b/en_US.ISO8859-1/articles/multi-os/Makefile deleted file mode 100644 index 8a591510bb..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $ - -DOCS= multios.docb -INDEXLINK= multios.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml deleted file mode 100644 index 849d1e07b9..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,682 +0,0 @@ -<!-- $Id: article.sgml,v 1.3 1998-05-19 13:39:50 stb Exp $ --> -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>Installing and Using FreeBSD With Other Operating Systems</title> - -<authorgroup> -<author> -<firstname>Jay</firstname> -<surname>Richmond</surname> -<affiliation> -<address> -<email>jayrich@sysc.com</email> -</address> -</affiliation> -</author> -</authorgroup> - -<pubdate>6 August 1996</pubdate> - -<abstract><para>This document discusses how to make FreeBSD coexist -nicely with other popular operating systems such as Linux, MS-DOS, -OS/2, and Windows 95. Special thanks to: Annelise Anderson -<email>andrsn@stanford.edu</email>, Randall Hopper -<email>rhh@ct.picker.com</email>, and Jordan K. Hubbard -<email>jkh@time.cdrom.com</email></para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Overview</title> - -<para>Most people can't fit these operating systems together -comfortably without having a larger hard disk, so special -information on large EIDE drives is included. Because there are so -many combinations of possible operating systems and hard disk -configurations, the <xref linkend="ch5"> section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems.</para> - -<para>This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the <filename>\TOOLS</filename> directory or via -<ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence.</para> - -</chapter> - -<chapter id="ch2"> -<title>Overview of Boot Managers</title> - -<para>These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system.</para> - -<variablelist> - -<varlistentry> -<term>Boot Easy</term> - -<listitem> -<para>This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys.</para> -</listitem> -</varlistentry> - -<varlistentry> -<term>OS/2 Boot Manager</term> - -<listitem> -<para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 -(Linux). It will also boot FAT32 partitions. Partitions are -selected using arrow keys. The OS/2 Boot Manager is the only one to -use its own separate partition, unlike the others which use the -master boot record (MBR). Therefore, it must be installed below the -1024th cylinder to avoid booting problems. It can boot Linux using -LILO when it is part of the boot sector, not the MBR. Go to <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOWTOs</ulink> -on the World Wide Web for more information on booting Linux with -OS/2's boot manager.</para> -</listitem> -</varlistentry> - -<varlistentry> -<term>OS-BS</term> - -<listitem> <para>This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -<filename>\TOOLS</filename> directory, and via <ulink -URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>.</para> -</listitem> </varlistentry> - -<varlistentry> -<term>LILO, or LInux LOader</term> - -<listitem> -<para>This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file.</para> -</listitem> -</varlistentry> - -</variablelist> - -<note id="fat32"><title>About FAT32</title><para>FAT32 is the replacement to -the FAT filesystem included in Microsoft's OEM SR2 Beta release, -which is expected to utilitized on computers pre-loaded with Windows -95 towards the end of 1996. It converts the normal FAT file system -and allows you to use smaller cluster sizes for larger hard drives. -FAT32 also modifies the traditional FAT boot sector and allocation -table, making it incompatible with some boot managers.</para></note> - -</chapter> - -<chapter id="ch3"> -<title>A Typical Installation</title> - -<para>Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them.</para> - -<para>Here's how I might do it using these hard disks: -<itemizedlist> - -<listitem> -<para><filename>/dev/wd0</> (first physical hard disk)</para> -</listitem> - -<listitem> -<para><filename>/dev/wd1</> (second hard disk)</para> -</listitem> - -</itemizedlist> -</para> - -<para>Both disks have 1416 cylinders.</para> - -<procedure> - -<step><para>I boot from a MS-DOS or Windows 95 boot disk that -contains the <filename>FDISK.EXE</> utility and make a small 50 meg -primary partition (35-40 for Windows 95, plus a little breathing -room) on the first disk. Also create a larger partition on the -second hard disk for my Windows applications and data.</para></step> - -<step><para>I reboot and install Windows 95 (easier said than done) -on the <filename>C:</> partition.</para> </step> - -<step><para>The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -<xref linkend="ch2">). When I am partitioning out my hard disk with -Linux <command>fdisk</command>, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space).</para></step> - -<step><para>After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record).</para></step> - -<step><para>The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the <filename>/usr</> and <filename>/</> slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the <filename>/usr/src</> slice and swap -space.</para></step> - -<step><para>When viewed with the Windows 95 <command>fdisk</> utility, my hard drives -should now look something like this: -<screen> ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- -</screen> -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See <xref linkend="ch2">).</para></step> - -<step><para>Install FreeBSD. I make sure to boot with my first hard -disk set at <quote>NORMAL</> in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (<filename>MSD.EXE</>), -or check your BIOS) with the parameter <literal>hd0=1416,16,63</> -where <replaceable>1416</> is the number of cylinders on my hard -disk, <replaceable>16</> is the number of heads per track, and -<replaceable>63</> is the number of sectors per track on the -drive.</para></step> - -<step><para>When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it.</para></step> - -<step><para>When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD).</para></step> - -</procedure> - -</chapter> - -<chapter id="ch4"> -<title>Special Considerations</title> - -<para>Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary partitiin on the first hard disk. OS/2 is the exception. It -can be installed on the first or second disk in a primary or extended -partition. If you are not sure, keep the beginning of the bootable -partitions below the 1024th cylinder.</para> - -<para>If you install Windows 95 on an existing BSD system, it will -<quote>destroy</> the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via <ulink -URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS.</para> - -<para>Please keep in mind that OS/2 can read FAT and HPFS partitions, -but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows -95 can only read and write to FAT and FAT32 (see <xref -linkend="ch2">) partitions. FreeBSD can read most file systems, but -currently cannot read HPFS partitions. Linux can read HPFS -partitions, but can't write to them. Recent versions of the Linux -kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT -is what gives Windows 95 long file names - it's pretty much the same -as FAT). Linux can read and write to most file systems. Got that? -I hope so.</para> - -</chapter> - -<chapter id="ch5"> -<title>Examples</title> - -<para><emphasis>(section needs work, please send your example to -<email>jayrich@sysc.com</email>)</emphasis>.</para> - -<para>FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see <literal>DOS</> on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read <xref -linkend="ch4"> above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like <errorname>invalid system disk</> under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called <quote>> 1024 cylinder support</> or <quote>NORMAL/LBA</> -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the <filename>FBSDBOOT.EXE</> utility on the CD (It should find your -FreeBSD partition and boot it.)</para> - -<para>FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem.</para> - -<para>FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems.</para> - -<para>FreeBSD+Linux+Win95: (see <xref linkend="ch3">)</para> - -</chapter> - -<chapter id="sources"> -<title>Other Sources of Help</title> - -<para>There are many <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOW-TOs</ulink> that -deal with multiple operating systems on the same hard disk.</para> - -<para>The <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 -mini-HOWTO</ulink> offers help on configuring the OS/2 boot manager, and the -<ulink -URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD -mini-HOWTO</ulink> might be interesting as well. The <ulink -URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> is -also helpful.</para> - -<para>The <ulink -URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT Loader -Hacking Guide</ulink> provides good information on multibooting -Windows NT, '95, and DOS with other operating systems.</para> - -<para>And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: <ulink URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>, -<ulink URL="http://web.idirect.com/~frank/">http://www.cs.yorku.ca/People/frank/docs/</ulink>.</para> - -<para>Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -<ulink URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para> - -</chapter> - -<chapter> -<title>Technical Details</title> - -<para><emphasis>(Contributed by Randall Hopper, -<email>rhh@ct.picker.com</email>)</emphasis></para> - -<para>This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading.</para> - - -<sect1> -<title>Disk Primer</title> - -<para>Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It's not -particularly important to know what these terms relate to except to -know that, together, they identify where data is physically on your -disk.</para> - -<para>Your disk has a particular number of cylinders, number of -heads, and number of sectors per cylinder-head (a cylinder-head also -known nown as a track). Collectively this information defines the -"physical disk geometry" for your hard disk. There are typically 512 -bytes per sector, and 63 sectors per track, with the number of -cylinders and heads varying widely from disk to disk. Thus you can -figure the number of bytes of data that'll fit on your own disk by -calculating: <informalexample><para>(# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect)</></informalexample> For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: <informalexample><para>(3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect)</para></informalexample></para> - -<para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para> - -<para>You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see <xref linkend="limits">), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. <filename>MSD.EXE</> or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -<firstterm>translated geometry</> (virtual numbers from using LBA). -Stay tuned for what that means.</para> - -<para>One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1.</para> - -<para>For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for <literal>boot -sector</> or <literal>master boot record</>. Among the useful info -you'll find are Hale Landis's <citetitle>How It Works</> document -pack. See the <xref linkend="sources"> section for a few pointers to -this pack.</para> - -<para>Ok, enough terminology. We're talking about booting -here.</para> - -</sect1> - -<sect1 id="booting"> -<title>The Booting Process</title> - -<para>On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 <firstterm>partitions</>, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -<firstterm>slices</> to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system.</para> - -<para>Each partition entry in the MBR has a <firstterm>Partition -ID</>, a <firstterm>Start Cylinder/Head/Sector</>, and an -<firstterm>End Cylinder/Head/Sector</>. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. <xref linkend="tbl-pid"> lists a smattering of some common -Partition IDs.</para> - -<table id="tbl-pid"> -<title>Partition IDs</> -<tgroup cols="2"> -<thead> -<row> -<entry>ID (hex)</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> -<row> -<entry>01</entry> -<entry>Primary DOS12 (12-bit FAT)</entry> -</row> - -<row> -<entry>04</entry> -<entry>Primary DOS16 (16-bit FAT)</entry> -</row> - -<row> -<entry>05</entry> -<entry>Extended DOS</entry> -</row> - -<row> -<entry>06</entry> -<entry>Primary big DOS (> 32MB)</entry> -</row> - -<row> -<entry>0A</entry> -<entry>OS/2</entry> -</row> - -<row> -<entry>83</entry> -<entry>Linux (EXT2FS)</entry> -</row> - -<row> -<entry>A5</entry> -<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Note that not all partitions are bootable (e.g. Extended DOS). -Some are—some aren't. What makes a partition bootable is the -configuration of the <firstterm>Partition Boot Sector</> that exists -at the beginning of each partition.</para> - -<para>When you configure your favorite boot manager, it looks up the entries -in the MBR partition tables of all your hard disks and lets you name the -entries in that list. Then when you boot, the boot manager is invoked by -special code in the Master Boot Sector of the first probed hard disk on -your system. It looks at the MBR partition table entry corresponding to -the partition choice you made, uses the Start Cylinder/Head/Sector -information for that partition, loads up the Partition Boot Sector for that -partition, and gives it control. That Boot Sector for the partition itself -contains enough information to start loading the operating system on that -partition.</para> - -<para>One thing we just brushed past that's important to know. All of your -hard disks have MBRs. However, the one that's important is the one on the -disk that's first probed by the BIOS. If you have only IDE hard disks, its -the first IDE disk (e.g. primary disk on first controller). Similarly for -SCSI only systems. If you have both IDE and SCSI hard disks though, the -IDE disk is typically probed first by the BIOS, so the first IDE disk is -the first probed disk. The boot manager you will install will be hooked into -the MBR on this first probed hard disk that we've just described.</para> - -</sect1> - -<sect1 id="limits"> -<title>Booting Limitations and Warnings</title> - -<para>Now the interesting stuff that you need to watch out for.</para> - -<sect2> -<title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title> - -<para>The first part of the booting process is all done through the -BIOS, (if that's a new term to you, the BIOS is a software chip on -your system motherboard which provides startup code for your -computer). As such, this first part of the process is subject to the -limitations of the BIOS interface.</para> - -<para>The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: -<itemizedlist> -<listitem><para>1024 cylinders, max</para></listitem> -<listitem><para>256 heads , max</para></listitem> -<listitem><para>64 cylinders, max (actually 63, <literal>0</> isn't -available)</para></listitem> -</itemizedlist> -</para> - -<para>Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can't boot off just anywhere on your hard disk. The boot code (the -boot manager and the OS loader hooked into all bootable partitions' -Boot Sectors) has to reside below cylinder 1024. In fact, if your -hard disk is typical and has 16 heads, this equates to: -<informalexample> -<para>1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector</para> -</informalexample> -</para> - -<para>which is around the often-mentioned 528MB limit.</para> - -<para>This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads).</para> - -<para>With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit.</para> - -<para>To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: -<informalexample> -<para>(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector)</para> -</informalexample> -</para> - -<para>However, my BIOS LBA remaps this to: -<informalexample> -<para>( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector)</para> -</informalexample> -</para> - -<para>giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA).</para> - -</sect2> - -<sect2> -<title>Boot Managers and Disk Allocation</title> - -<para>Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs.</para> - -<para>If you followed the discussion in <xref linkend="booting"> -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically.</para> - -<para>That's the catch. Some operating systems (FreeBSD included) let -you start their partitions right after the Master Boot Sector at -Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give -FreeBSD's sysinstall a disk with an empty chunk up front or the whole -disk empty, that's where it'll start the FreeBSD partition by default -(at least it did when I fell into this trap). Then when you go to -install your boot manager, if it's one that occupies a few extra -sectors after the MBR, it'll overwrite the front of the first -partition's data. In the case of FreeBSD, this overwrites the -disk label, and renders your FreeBSD partition unbootable.</para> - -<para>The easy way to avoid this problem (and leave yourself the -flexibility to try different boot managers later) is just to always -leave the first full track on your disk unallocated when you -partition your disk. That is, leave the space from Cylinder 0, Head -0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and -start your first partition at Cylinder 0, Head 1, Sector 1. -For what it's worth, when you create a DOS partition at the -front of your disk, DOS leaves this space open by default (this is -why some boot managers assume it's free). So creating a DOS -partition up at the front of your disk avoids this problem -altogether. I like to do this myself, creating 1 Meg DOS partition -up front, because it also avoids my primary DOS drive letters -shifting later when I repartition.</para> - -<para>For reference, the following boot managers use the -Master Boot Sector to store their code and data: -<itemizedlist> - -<listitem> -<para>OS-BS 1.35</para> -</listitem> - -<listitem> -<para>Boot Easy</para> -</listitem> - -<listitem> -<para>LILO</para> -</listitem> - -</itemizedlist> -</para> - -<para>These boot managers use a few additional sectors after the -Master Boot Sector: -<itemizedlist> - -<listitem> -<para>OS-BS 2.0 Beta 8 (sectors 2-5)</para> -</listitem> - -<listitem> -<para>OS/2's boot manager</para> -</listitem> - -</itemizedlist> -</para> - -</sect2> - -<sect2> -<title>What if your machine won't boot?</title> - -<para>At some point when installing boot managers, you might leave the -MBR in a state such that your machine won't boot. This is unlikely, -but possible when re-FDISKing underneath an already-installed boot -manager.</para> - -<para>If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: -<informalexample> -<screen>A:\> <userinput>FDISK /MBR</></screen> -</informalexample> -</para> - -<para>to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy.</para> - -</sect2> -</sect1> -</chapter> -</book> diff --git a/en_US.ISO8859-1/articles/new-users/Makefile b/en_US.ISO8859-1/articles/new-users/Makefile deleted file mode 100644 index d8131087f4..0000000000 --- a/en_US.ISO8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $ - -DOCS= newuser.docb -INDEXLINK= newuser.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml deleted file mode 100644 index 9c3baeb6b5..0000000000 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,943 +0,0 @@ -<!-- $Id: article.sgml,v 1.5 1998-08-09 22:53:56 wosch Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>For People New to Both FreeBSD and Unix</title> - -<authorgroup> -<author> -<firstname>Annelise</firstname> -<surname>Anderson</surname> -<affiliation> -<address><email>andrsn@andrsn.stanford.edu</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>August 15, 1997</pubdate> - -<abstract><para>Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -<emphasis>and</emphasis> Un*x—so it starts with basics. It -assumes you're using version 2.0.5 or later of FreeBSD as distributed -by Walnut Creek or FreeBSD.ORG, your system (for now) has a single -user (you)—and you're probably pretty good with DOS/Windows or -OS/2.</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Logging in and Getting Out</title> - -<para>Log in (when you see <systemitem -class=prompt>login:</systemitem>) as a user you created during -installation or as <firstterm>root</firstterm>. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. </para> - -<para>To log out (and get a new <systemitem class=prompt>login:</systemitem> prompt) type -<informalexample> -<screen># <userinput>exit</userinput></screen> -</informalexample> -as often as necessary. Yes, press <keysym>enter</keysym> after -commands, and remember that Unix is -case-sensitive—<command>exit</command>, not -<command>EXIT</command>.</para> - -<para>To shut down the machine type: -<informalexample> -<screen># <userinput>/sbin/shutdown -h now</userinput></screen> -</informalexample> -Or to reboot type -<informalexample> -<screen># <userinput>/sbin/shutdown -r now</userinput></screen> -</informalexample> -or -<informalexample> -<screen># <userinput>/sbin/reboot</userinput></screen> -</informalexample> -</para> - -<para>You can also reboot with -<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. -Give it a little time to do its work. This is equivalent to -<command>/sbin/reboot</command> in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you?</para> - -</chapter> - -<chapter> -<title>Adding A User with Root Privileges</title> - -<para>If you didn't create any users when you installed the system and -are thus logged in as root, you should probably create a user now with -<informalexample> -<screen># <userinput>adduser</userinput></screen> -</informalexample> -The first time you use adduser, it might ask for some defaults to save. You -might want to make the default shell csh instead of sh, if it suggests -sh as the default. Otherwise just press enter to accept each default. -These defaults are saved in <filename>/etc/adduser.conf</filename>, -an editable file.</para> - -<para>Suppose you create a user <emphasis>jack</emphasis> with -full name <emphasis>Jack Benimble</emphasis>. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type <userinput>wheel</userinput> -<informalexample> -<screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen> -</informalexample> -This will make it possible to log in as <emphasis>jack</emphasis> and -use the <command>su</command> command to become root. Then you won't -get scolded any more for logging in as root.</para> - -<para>You can quit <command>adduser</command> any time by typing -<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, and at -the end you'll have a chance to approve your new user or simply type -<keycap>n</keycap> for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong.</para> - -<para>Once you've done this, use <command>exit</command> -to get back to a login prompt and log in as -<emphasis>jack</emphasis>. In general, it's a good idea to do as -much work as possible as an ordinary user who doesn't have the -power—and risk—of root.</para> - -<para>If you already created a user and you want the user to be able -to <command>su</command> to root, you can log in as root -and edit the file <filename>/etc/group</filename>, adding jack to the -first line (the group wheel). But first you need to practice -<command>vi</command>, the text editor--or use the simpler text -editor, <command>ee</command>, installed on recent version of -FreeBSD.</para> - -<para>To delete a user, use the <command>rmuser</command> command.</para> - -</chapter> - -<chapter> -<title>Looking Around</title> - -<para>Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD.</para> - -<para>Here are some commands and what they do: -<variablelist> -<varlistentry><term><command>id</command></term> -<listitem> -<para>Tells you who you are!</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>pwd</command></term> - -<listitem> -<para>Shows you where you are—the current -working directory.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls</command></term> - -<listitem> -<para>Lists the files in the current directory.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-F</option></command></term> - -<listitem> -<para>Lists the files in the current directory with a -<literal>*</literal> after executables, a <literal>/</literal> after -directories, and an <literal>@</literal> after symbolic links.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-l</option></command></term> - -<listitem> -<para>Lists the files in long format—size, -date, permissions.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-a</option></command></term> - -<listitem> -<para>Lists hidden <quote>dot</quote> -files with the others. If you're root, the<quote>dot</quote> files -show up without the <option>-a</option> switch.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>cd</command></term> - -<listitem> -<para>Changes directories. <command>cd -<parameter>..</parameter></command> backs up one level; note the -space after <command>cd</command>. <command>cd -<parameter>/usr/local</parameter></command> goes there. <command>cd -<parameter>~</parameter></command> goes to the home directory of the -person logged in—e.g., <filename>/usr/home/jack</filename>. -Try <command>cd <parameter>/cdrom</parameter></command>, and then -<command>ls</command>, to find out if your CDROM is mounted and -working.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>view <replaceable>filename</replaceable></command></term> - -<listitem> -<para>Lets you look at a file (named -<replaceable>filename</replaceable> without changing it. Try -<command>view <parameter>/etc/fstab</parameter></command>. -<command>:q</command> to quit.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>cat <replaceable>filename</replaceable></command></term> - -<listitem> - -<para>Displays <replaceable>filename</replaceable> on screen. If -it's too long and you can see only the end of it, press -<keycap>ScrollLock</keycap> and use the <keycap>up-arrow</keycap> to -move backward; you can use <keycap>ScrollLock</keycap> with man pages -too. Press <keycap>ScrollLock</keycap> again to quit scrolling. You -might want to try <command>cat</command> on some of the dot files in -your home directory—<command>cat -<parameter>.cshrc</parameter></command>, <command>cat -<parameter>.login</parameter></command>, <command>cat -<parameter>.profile</parameter></command>.</para> - -</listitem> -</varlistentry> -</variablelist> - -You'll notice aliases in <filename>.cshrc</filename> for some of the -<command>ls</command> commands (they're very convenient). -You can create other aliases by editing <filename>.cshrc</filename>. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -<filename>/etc/csh.cshrc</filename>.</para> - -</chapter> - -<chapter> -<title>Getting Help and Information</title> - -<para>Here are some useful sources of help. -<replaceable>Text</replaceable> stands for something of your choice -that you type in—usually a command or filename.</para> - -<variablelist> -<varlistentry><term><command>apropos <replaceable>text</replaceable></command></term> - -<listitem> -<para>Everything containing string <replaceable>text</replaceable> -in the <database>whatis database</database>.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>man <replaceable>text</replaceable></command></term> - -<listitem> -<para>The man page for <replaceable>text</replaceable>. The major -source of documentation for Un*x systems. <command>man -<parameter>ls</parameter></command> will tell you all the ways to use -the <command>ls</command> command. Press <keycap>Enter</keycap> to -move through text, -<keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> to go -back a page, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo> to -go forward, <keycap>q</keycap> or -<keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo> to -quit.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>which <replaceable>text</replaceable></command></term> - -<listitem> -<para>Tells you where in the user's path the command -<replaceable>text</replaceable> is found.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>locate <replaceable>text</replaceable></command></term> - -<listitem> -<para>All the paths where the string <replaceable>text</replaceable> -is found.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>whatis <replaceable>text</replaceable></command></term> - -<listitem> -<para>Tells you what the command <replaceable>text</replaceable> -does and its man page. Typing <command>whatis *</command> will tell -you about all the binaries in the current directory.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>whereis <replaceable>text</replaceable></command></term> - -<listitem> -<para>Finds the file <replaceable>text</replaceable>, giving its full -path.</para> -</listitem> -</varlistentry> -</variablelist> - -<para>You might want to try using <command>whatis</command> on some -common useful commands like <command>cat</command>, -<command>more</command>, <command>grep</command>, -<command>mv</command>, <command>find</command>, -<command>tar</command>, <command>chmod</command>, -<command>chown</command>, <command>date</command>, and -<command>script</command>. <command>more</command> lets you read a -page at a time as it does in DOS, e.g., <command>ls -l | -more</command> or <command>more -<replaceable>filename</replaceable></command>. The -<literal>*</literal> works as a wildcard—e.g., <command>ls -w*</command> will show you files beginning with -<literal>w</literal>.</para> - -<para>Are some of these not working very well? Both -<command>locate</command> and <command>whatis</command> -depend on a database that's rebuilt weekly. If your machine isn't -going to be left on over the weekend (and running FreeBSD), you might -want to run the commands for daily, weekly, and monthly maintenance -now and then. Run them as root and give each one time to finish -before you start the next one, for now. -<informalexample> -<screen># <userinput>/etc/daily</userinput> -<lineannotation>output omitted</lineannotation> -# <userinput>/etc/weekly</userinput> -<lineannotation>output omitted</lineannotation> -# <userinput>/etc/monthly</userinput> -<lineannotation>output omitted</lineannotation></screen> -</informalexample></para> - -<para>If you get tired waiting, press -<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to get -another <firstterm>virtual console</firstterm>, and log in again. -After all, it's a multi-user, multi-tasking system. Nevertheless -these commands will probably flash messages on your screen while -they're running; you can type <command>clear</command> at the prompt -to clear the screen. Once they've run, you might want to look at -<filename>/var/mail/root</filename> and -<filename>/var/log/messages</filename>.</para> - -<para>Basically running such commands is part of system -administration—and as a single user of a Unix system, you're -your own system administrator. Virtually everything you need to be -root to do is system administration. Such responsibilities aren't -covered very well even in those big fat books on Unix, which seem to -devote a lot of space to pulling down menus in windows managers. You -might want to get one of the two leading books on systems -administration, either Evi Nemeth et.al.'s <citetitle>UNIX System -Administration Handbook</citetitle> (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's <citetitle>Essential System -Administration</citetitle> (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth.</para> - -</chapter> - -<chapter> -<title>Editing Text</title> - -<para>To configure your system, you need to edit text files. Most of -them will be in the <filename>/etc</filename> directory; and you'll -need to <command>su</command> to root to be able to change them. You -can use the easy <command>ee</command>, but in the long run the -text editor <command>vi</command> is worth learning. There's an -excellent tutorial on vi in -<filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para> - -<para>Before you edit a -file, you should probably back it up. Suppose you want to edit -<filename>/etc/rc.conf</filename>. You could just use <command>cd -/etc</command> to get to the <filename>/etc</filename> directory and -do: -<informalexample> -<screen># <userinput>cp rc.conf rc.conf.orig</userinput></screen> -</informalexample> - -This would copy <filename>rc.conf</filename> to -<filename>rc.conf.orig</filename>, and you could later copy -<filename>rc.conf.orig</filename> to <emphasis -remap=tt>rc.conf</emphasis> to recover the original. But even -better would be moving (renaming) and then copying back: -<informalexample> -<screen># <userinput>mv rc.conf rc.conf.orig</userinput> -# <userinput>cp rc.conf.orig rc.conf</userinput></screen> -</informalexample> - -because the <command>mv</command> command preserves the original date -and owner of the file. You can now edit -<filename>rc.conf</filename>. If you want the original back, you'd -then <userinput>mv rc.conf rc.conf.myedit</userinput> -(assuming you want to preserve your edited version) and then -<informalexample> -<screen># <userinput>mv rc.conf.orig rc.conf</userinput></screen> -</informalexample> -to put things back the way they were.</para> - -<para>To edit a file, type -<informalexample> -<screen># <userinput>vi <replaceable>filename</replaceable></userinput></screen> -</informalexample> -Move through the text with the arrow keys. <keycap>Esc</keycap> (the -escape key) puts <command>vi</command> in command mode. Here are some -commands: -<variablelist> -<varlistentry><term><command>x</command></term> -<listitem> -<para>delete letter the cursor is on</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>dd</command></term> - -<listitem> -<para>delete the entire line (even if it wraps on the screen)</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>i</command></term> - -<listitem> -<para>insert text at the cursor</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>a</command></term> - -<listitem> -<para>insert text after the cursor</para> - -</listitem> -</varlistentry> -</variablelist> -Once you type <command>i</command> or <command>a</command>, you can enter text. -<command>Esc</command> puts you back in command mode where you can type -<variablelist> -<varlistentry><term><command>:w</command></term> -<listitem> -<para>to write your changes to disk and continue editing</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>:wq</command></term> - -<listitem> -<para>to write and quit</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>:q!</command></term> - -<listitem> -<para>to quit without saving changes</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>/<replaceable>text</replaceable></command></term> - -<listitem> -<para>to move the cursor to <replaceable>text</replaceable>; -<command>/<keycap>Enter</keycap></command> (the enter key) to find -the next instance of <replaceable>text</replaceable>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>G</command></term> - -<listitem> -<para>to go to the end of the file</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command><replaceable>n</replaceable>G</command></term> - -<listitem> -<para>to go to line <replaceable>n</replaceable> in -the file, where <replaceable>n</replaceable> is a number</para> - -</listitem> -</varlistentry> - -<varlistentry><term><keycombo><keycap>Ctrl</><keycap>L</></keycombo></term> - -<listitem> -<para>to redraw the screen</para> - -</listitem> -</varlistentry> - -<varlistentry><term><keycombo><keycap>Ctrl</><keycap>b</></> and <keycombo><keycap>Ctrl</><keycap>f</></></term> - -<listitem> -<para>go back -and forward a screen, as they -do with <command>more</> and <command>view</>.</para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -<para>Practice with <command>vi</> in your home directory by creating -a new file with <command>vi <replaceable>filename</></> and adding -and deleting text, saving the file, and calling it up again. -<command>vi</> delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -<command>vi</>—it's more powerful than DOS EDIT—find out -about the <command>:r</> command.) Use <keycap>Esc</> one or -more times to be sure you're in command mode and proceed from there -when it gives you trouble, save often with <command>:w</>, and -use <command>:q!</> to get out and start over (from -your last <command>:w</>) when you need to.</para> - -<para>Now you can <command>cd</> to <filename>/etc</filename>, -<command>su</> to root, use <command>vi</> to edit the file -<filename>/etc/group</filename>, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press <keycap>Esc</>, and use -<command>:wq</> to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?)</para> - -</chapter> - -<chapter> -<title>Printing Files from DOS</title> - -<para>At this point you probably don't have the printer working, so here's a -way to create a file from a man page, move it to a floppy, and then -print it from DOS. Suppose you want to read carefully about changing -permissions on files (pretty important). You can use the command -man chmod to read about it. The command -<informalexample> -<screen># <userinput>man chmod | col -b > chmod.txt</></screen> -</informalexample> -will remove formatting codes and send the man page to -the <filename>chmod.txt</filename> file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, <command>su</> to -root, and type -<informalexample> -<screen># <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</></screen> -</informalexample> -to mount the floppy drive on <filename>/mnt</filename>.</para> - -<para>Now (you no longer need to be root, and you can type -<command>exit</> to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: -<informalexample> -<screen>% <userinput>cp chmod.txt /mnt</></screen> -</informalexample> -and use <command>ls /mnt</command> to get a directory listing of -<filename>/mnt</filename>, which should show the file -<filename>chmod.txt</filename>.</para> - -<para>You might especially want to make a file from -<filename>/sbin/dmesg</filename> by typing -<informalexample> -<screen>% <userinput>/sbin/dmesg > dmesg.txt</></screen> -</informalexample> -and copying <filename>dmesg.txt</filename> to the floppy. -<command>/sbin/dmesg</command> is the boot log record, and it's -useful to understand it because it shows what FreeBSD found when it -booted up. If you ask questions on -<email>freebsd-questions@FreeBSD.ORG</> or on a USENET -group—like <quote>FreeBSD isn't finding my tape drive, what do -I do?</quote>—people will want to know what <command>dmesg</> -has to say.</para> - -<para>You can now dismount the floppy drive (as root) to get the disk -out with -<informalexample> -<screen># <userinput>/sbin/umount /mnt</></screen> -</informalexample> -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a -minor change so the file has to be saved, and print as you normally -would from DOS or Windows. Hope it works! man pages come out best if -printed with the dos <command>print</> command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.)</para> - -<para>Getting the printer printing from FreeBSD involves creating an -appropriate entry in <filename>/etc/printcap</filename> and creating -a matching spool directory in -<filename>/var/spool/output</filename>. If your printer is on -<hardware>lpt0</> (what dos calls <hardware>LPT1</>), you may only -need to go to <filename>/var/spool/output</filename> and (as root) -create the directory <filename>lpd</> by typing: -<command> -mkdir lpd</command>, if it doesn't already -exist. -Then the printer should respond if it's turned on when the system is -booted, and lp or lpr should send a file to the printer. Whether or -not the file actually prints depends on configuring it, which is -covered in the <ulink -URL="../../handbook/handbook.html">FreeBSD -handbook.</></para> - -</chapter> - -<chapter> -<title>Other Useful Commands</title> - -<para> -<variablelist> -<varlistentry><term><command>df</></term> -<listitem> -<para>shows file space and mounted systems.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ps aux</></term> - -<listitem> -<para>shows processes running. <command>ps ax</> is a narrower form.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>rm <replaceable>filename</></></term> - -<listitem> -<para>remove <replaceable>filename</>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>rm -R <replaceable>dir</></></term> - -<listitem> -<para>removes a directory <replaceable>dir</> and all -subdirectories—careful!</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls -R</command></term> - -<listitem> -<para>lists files in the current -directory and all subdirectories; -I used a variant, <command>ls -AFR > where.txt</command>, -to get a list of all -the files in <filename>/</filename> and (separately) -<filename>/usr</filename> before I found better -ways to find files.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>passwd</></term> - -<listitem> -<para>to change user's password (or root's password)</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>man hier</></term> - -<listitem> -<para>man page on the Unix file system</para> - -</listitem> -</varlistentry> -</variablelist></para> - -<para>Use <command>find</> to locate filename in <filename>/usr</filename> -or any of its subdirectories with -<informalexample> -<screen>% <userinput>find /usr -name "<replaceable>filename</>"</></screen> -</informalexample> -You can use <literal>*</literal> as a wildcard in -<parameter>"<replaceable>filename</>"</> (which should be in -quotes). If you tell find to search in <filename>/</filename> -instead of <filename>/usr</filename> it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition.</para> - -<para>An excellent book that explains Unix commands and utilities is -Abrahams & Larson, <citetitle>Unix for the Impatient</citetitle> -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the <ulink -URL="http://www.eecs.nwu.edu/unix.html">Unix Reference -Desk</ulink>.</para> - -</chapter> - -<chapter> -<title>Next Steps</title> - -<para>You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and <ulink URL="http://www.freebsd.org/">FreeBSD's -web site</ulink>. A wide variety of packages and ports are on the -<ulink URL="http://www.cdrom.com/">Walnut Creek</ulink> CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with <command>pkg_add -/cdrom/packages/All/<replaceable>packagename</></>, -where <replaceable>packagename</replaceable> is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in <filename>cdrom/packages/index</filename>, -<filename>cdrom/packages/index.txt</filename>, and -<filename>cdrom/ports/index</filename>, with fuller descriptions in -<filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the -<literal>*</literal>s represent subdirectories of kinds of programs -and program names respectively.</para> - -<para>If you find the handbook too sophisticated (what with -<command>lndir</> and all) on installing ports from the cdrom, -here's what usually works:</para> - -<para>Find the port you want, say <command>kermit</>. There will be -a directory for it on the cdrom. Copy the subdirectory to -<filename>/usr/local</filename> (a good place for software you add -that should be available to all users) with: -<informalexample> -<screen># <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</></screen> -</informalexample> - -This should result in a <filename>/usr/local/kermit</filename> -subdirectory that has all the files that the -<command>kermit</command> subdirectory on the CDROM has.</para> - -<para>Next, create the directory <filename>/usr/ports/distfiles</filename> -if it doesn't already exist using <command>mkdir</>. Now check -check <filename>/cdrom/ports/distfiles</filename> for a -file with a name that indicates it's the port you want. Copy that -file to <filename>/usr/ports/distfiles</filename>; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of <command>kermit</>, there is no -distfile.</para> - -<para>Then <command>cd</> to the subdirectory of -<filename>/usr/local/kermit</filename> that has the file -<filename>Makefile</>. Type -<informalexample> -<screen># <userinput>make all install</></screen> -</informalexample> -</para> - -<para>During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -<filename>/usr/ports/distfiles</filename>. If you don't have your -network running yet and there was no file for the port in -<filename>/cdrom/ports/distfiles</filename>, you will have to get -the distfile using another machine and copy it to -<filename>/usr/ports/distfiles</filename> from a floppy or your dos -partition. Read <filename>Makefile</> (with <command>cat</> or -<command>more</> or <command>view</>) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into <filename>/usr/ports/distfiles</filename> you'll have to rename -it (with the <command>mv</> command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -<filename>/usr/local/kermit</filename>, find the directory with -<filename>Makefile</>, and type <command>make all install</>.</para> - -<para>The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message <errorname>can't find unzip</errorname> or whatever, you -might need to install the package or port for unzip before you -continue.</para> - -<para>Once it's installed type <command>rehash</> to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of <errorname>path not found</> messages when you use -<command>whereis</> or which, you might want to make additions to the -list of directories in the path statement in -<filename>.cshrc</filename> in your home directory. The path -statement in Unix does the same kind of work it does in DOS, except -the current directory is not (by default) in the path for security -reasons; if the command you want is in the directory you're in, you -need to type <filename>./</filename> before the command to make it -work; no space after the slash.)</para> - -<para>You might want to get the most recent version of Netscape from -their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use <command>gunzip -<replaceable>filename</></> and <command>tar xvf -<replaceable>filename</></> on it, move the binary to -<filename>/usr/local/bin</filename> or some other place binaries are -kept, <command>rehash</>, and then put the following lines in -<filename>.cshrc</filename> in each user's home directory or (easier) -in <filename>/etc/csh.cshrc</filename>, the system-wide csh start-up -file: -<informalexample> -<programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls</> -</informalexample> -This assumes that the file <filename>XKeysymDB</> and the directory -<filename>nls</> are in <filename>/usr/X11R6/lib/X11</filename>; if -they're not, find them and put them there.</para> - -<para>If you originally got Netscape as a port using the CDROM (or -ftp), don't replace <filename>/usr/local/bin/netscape</filename> with -the new netscape binary; this is just a shell script that sets up the -environmental variables for you. Instead rename the new binary to -<filename>netscape.bin</filename> and replace the old binary, which -is <filename>/usr/local/lib/netscape/netscape.bin</filename>.</para> - -</chapter> - -<chapter> - -<title>Your Working Environment</title> - -<para>Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention.</para> - -<para>Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing <command>echo $SHELL</command>.</para> - -<para>The csh shell is okay, but tcsh does everything csh does and more. It -It allows you to recall commands with the arrow keys and edit them. -It has tab-key completion -of filenames (csh uses the escape key), and it lets you switch to the -directory you were last in with <command>cd -</command>. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier.</para> - -<para>Here are the three steps for installing a new shell:</para> - -<para> 1. Install the shell as a port or a package, just as you -would any other port or package. Use <command>rehash</command> and -<command>which tcsh</command> (assuming you're installing tcsh) to -make sure it got installed.</para> - -<para> 2. As root, edit <filename>/etc/shells</filename>, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.)</para> - -<para> 3. Use the <command>chsh</command> command to change your shell to -tcsh permanently, or type <command>tcsh</command> at the prompt to -change your shell without logging in again.</para> - -<para><emphasis>Note: It can be dangerous to change root's shell</emphasis> -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use <command>su -m</command> -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -<filename>.tcshrc</filename> file as an alias with <programlisting>alias su su -m.</></para> - -<para>When tcsh starts up, it will read the -<filename>/etc/csh.cshrc</filename> and <filename>/etc/csh.login</filename> -files, as does csh. It will also read the -<filename>.login</filename> file in your home directory and the -<filename>.cshrc</filename> -file as well, unless you provide a <filename>.tcshrc</filename> -file. This you can do by simply copying <filename>.cshrc</filename> -to <filename>.tcshrc</filename>.</para> - -<para>Now that you've installed tcsh, you can adjust your prompt. You can -find the details in the manual page for tcsh, but here is a line to -put in your <filename>.tcshrc</filename> that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a <literal>></literal> if you're an ordinary user and -a <literal>#</literal> if you're root, but tsch will do that in any -case:</para> -<para> - set prompt = "%h %t %~ %# "</para> - -<para>This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the <filename>.tcshrc</filename> reread by typing <command>source .tcshrc</command>.</para> - -<para>You can get a listing of other environmental variables that -have been set by typing <command>env</command> at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -<command>setenv TERM vt100</command>.</para> -</chapter> - - -<chapter> -<title>Other</title> - -<para>As root, you can dismount the CDROM with <command>/sbin/umount -/cdrom</>, take it out of the drive, insert another one, and mount it -with <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</> assuming -<hardware>cd0a</> is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -<command>/sbin/mount /cdrom</command>.</para> - -<para>Using the live file system—the second of FreeBSD's CDROM -disks—is useful if you've got limited space. What is on the -live file system varies from release to release. You might try -playing games from the cdrom. This -involves using <command>lndir</>, which gets installed with the X -Window System, to tell the program(s) where to find the necessary -files, because they're in the <filename>/cdrom</filename> file system -instead of in <filename>/usr</filename> and its subdirectories, which -is where they're expected to be. Read <command>man lndir</>.</para> - -</chapter> - -<chapter> -<title>Comments Welcome</title> - -<para>If you use this guide I'd be interested in knowing where it was -unclear and what was left out that you think should be included, and -if it was helpful. My thanks to Eugene W. Stark, professor of -computer science at SUNY-Stony Brook, and John Fieber for helpful -comments.</para> - -<para>Annelise Anderson, <email>andrsn@andrsn.stanford.edu</></para> - -</chapter> -</book> diff --git a/en_US.ISO8859-1/articles/programming-tools/Makefile b/en_US.ISO8859-1/articles/programming-tools/Makefile deleted file mode 100644 index 72c7507f01..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $ - -DOCS= devel.docb -INDEXLINK= devel.html - -.include "../../web.mk" - diff --git a/en_US.ISO8859-1/articles/programming-tools/article.sgml b/en_US.ISO8859-1/articles/programming-tools/article.sgml deleted file mode 100644 index 65e1f87d26..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/article.sgml +++ /dev/null @@ -1,1835 +0,0 @@ -<!-- $Id: article.sgml,v 1.4 1998-08-09 22:53:51 wosch Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> -<bookinfo> -<bookbiblio> -<title>A User's Guide to FreeBSD Programming Tools</title> - -<authorgroup> -<author> -<firstname>James</firstname> -<surname>Raynard</surname> -<affiliation> -<address> -<email>jraynard@freebsd.org</email> -</address> -</affiliation> -</author></authorgroup> - -<pubdate>August 17, 1997</pubdate> - -<copyright> -<year>1997</year> -<holder>James Raynard</holder> -</copyright> - -<abstract><para>This document is an introduction to using some of the programming -tools supplied with FreeBSD, although much of it will be applicable to -many other versions of Unix. It does <emphasis>not</emphasis> attempt to describe -coding in any detail. Most of the document assumes little or no -previous programming knowledge, although it is hoped that most -programmers will find something of value in it</para></abstract> -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction<anchor id=foo></title> - -<para>FreeBSD offers an excellent development environment. Compilers -for C, C++, and Fortran and an assembler come with the basic system, -not to mention a Perl interpreter and classic Unix tools such as -<command>sed</> and <command>awk</>. If that is not enough, there are -many more compilers and interpreters in the Ports collection. FreeBSD -is very compatible with standards such as <acronym>POSIX</> and -<acronym>ANSI</> C, as well with its own BSD heritage, so it is -possible to write applications that will compile and run with little -or no modification on a wide range of platforms.</para> - -<para>However, all this power can be rather overwhelming at first if -you've never written programs on a Unix platform before. This -document aims to help you get up and running, without getting too -deeply into more advanced topics. The intention is that this document -should give you enough of the basics to be able to make some sense of -the documentation.</para> - -<para>Most of the document requires little or no knowledge of -programming, although it does assume a basic competence with using -Unix and a willingness to learn!</para> - -</chapter> - -<chapter> -<title>Introduction to Programming</title> - -<para>A program is a set of instructions that tell the computer to do -various things; sometimes the instruction it has to perform depends -on what happened when it performed a previous instruction. This -section gives an overview of the two main ways in which you can give -these instructions, or <quote>commands</quote> as they are usually -called. One way uses an <firstterm>interpreter</>, the other a -<firstterm>compiler</>. As human languages are too difficult for a -computer to understand in an unambiguous way, commands are usually -written in one or other languages specially designed for the -purpose.</para> - - - -<sect1> -<title>Interpreters</title> - -<para>With an interpreter, the language comes as an environment, where you -type in commands at a prompt and the environment executes them for -you. For more complicated programs, you can type the commands into a -file and get the interpreter to load the file and execute the commands -in it. If anything goes wrong, many interpreters will drop you into a -debugger to help you track down the problem.</para> - -<para>The advantage of this is that you can see the results of your -commands immediately, and mistakes can be corrected readily. The -biggest disadvantage comes when you want to share your programs with -someone. They must have the same interpreter, or you must have some -way of giving it to them, and they need to understand how to use it. -Also users may not appreciate being thrown into a debugger if they -press the wrong key! From a performance point of view, interpreters -can use up a lot of memory, and generally do not generate code as -efficiently as compilers.</para> - -<para>In my opinion, interpreted languages are the best way to start -if you have not done any programming before. This kind of environment -is typically found with languages like Lisp, Smalltalk, Perl and -Basic. It could also be argued that the Unix shell (<command>sh</>, -<command>csh</>) is itself an interpreter, and many people do in fact -write shell <quote>scripts</quote> to help with various -<quote>housekeeping</> tasks on their machine. Indeed, part of the -original Unix philosophy was to provide lots of small utility -programs that could be linked together in shell scripts to perform -useful tasks.</para> - -</sect1> - -<sect1> -<title>Interpreters available with FreeBSD</title> - -<para>Here is a list of interpreters that are available as <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/">FreeBSD -packages</ulink>, with a brief discussion of some of the more popular -interpreted languages. </para> - -<para>To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -<screen>$ <userinput>pkg_add <replaceable>package name</></userinput></screen> -</para> - -<para>as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work!</para> - -<para> -<variablelist> -<varlistentry><term><acronym>BASIC</></term> - -<listitem><para>Short for Beginner's All-purpose Symbolic Instruction -Code. Developed in the 1950s for teaching University students to -program and provided with every self-respecting personal computer in -the 1980s, <acronym>BASIC</> has been the first programming language -for many programmers. It's also the foundation for <trademark>Visual -Basic</>.</para> - -<para>The <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater -Basic Interpreter</ulink> and the <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil -Cockroft's Basic Interpreter</ulink> (formerly Rabbit Basic) are -available as FreeBSD <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/">FreeBSD -packages</ulink></para> -</listitem> -</varlistentry> - -<varlistentry><term>Lisp</term> -<listitem><para>A language that was developed in the late 1950s as an alternative to -the <quote>number-crunching</quote> languages that were popular at the time. -Instead of being based on numbers, Lisp is based on lists; in fact -the name is short for <quote>List Processing</quote>. Very popular in AI -(Artificial Intelligence) circles.</para> - -<para>Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. </para> - -<para>FreeBSD has <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU -Common Lisp</ulink> available as a package.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Perl</term> -<listitem><para>Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing <acronym>CGI</> -scripts.</para> - -<para>Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/perl-5.001.tgz">Perl -Version 5</ulink> is available as a package.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Scheme</term> -<listitem><para>A dialect of Lisp that is rather more compact and -cleaner than Common Lisp. Popular in Universities as it is simple -enough to teach to undergraduates as a first language, while it has a -high enough level of abstraction to be used in research work.</para> - -<para>FreeBSD has packages of the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk Scheme Interpreter</ulink>, the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT Scheme Interpreter</ulink> and the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM Scheme Interpreter</ulink>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Icon</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The Icon Programming Language</ulink>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Logo</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian Harvey's LOGO Interpreter</ulink>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Python</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/python-1.2">The Python Object-Oriented Programming Language</ulink></para> -</listitem> -</varlistentry> - -</variablelist> -</para> - -</sect1> - -<sect1> -<title>Compilers</title> - -<para>Compilers are rather different. First of all, you write your -code in a file (or files) using an editor. You then run the compiler -and see if it accepts your program. If it did not compile, grit your -teeth and go back to the editor; if it did compile and gave you a -program, you can run it either at a shell command prompt or in a -debugger to see if it works properly.<footnote><para>If you run it in -the shell, you may get a core dump.</para></footnote></para> - -<para>Obviously, this is not quite as direct as using an interpreter. -However it allows you to do a lot of things which are very difficult -or even impossible with an interpreter, such as writing code which -interacts closely with the operating system—or even writing -your own operating system! It's also useful if you need to write very -efficient code, as the compiler can take its time and optimise the -code, which would not be acceptable in an interpreter. And -distributing a program written for a compiler is usually more -straightforward than one written for an interpreter—you can just -give them a copy of the executable, assuming they have the same -operating system as you.</para> - -<para>Compiled languages include Pascal, C and C++. C and C++ are rather -unforgiving languages, and best suited to more experienced -programmers; Pascal, on the other hand, was designed as an educational -language, and is quite a good language to start with. Unfortunately, -FreeBSD doesn't have any Pascal support, except for a Pascal-to-C -converter in the ports.</para> - -<para>As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (<acronym>IDE</acronym>s -for short). FreeBSD does not have an <acronym>IDE</> as such; however -it is possible to use Emacs for this purpose. This is discussed in -<xref linkend="emacs">.</para> - -</sect1> -</chapter> - -<chapter> -<title>Compiling with <command>cc</command></title> - -<para>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 <command>cc</> or <command>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 interpreter.</para> - -<para>Once you've written your masterpiece, the next step is to convert it -into something that will (hopefully!) run on FreeBSD. This usually -involves several steps, each of which is done by a separate -program.</para> - -<procedure> -<step><para>Pre-process your source code to remove comments and do other -tricks like expanding macros in C. -</para></step> - -<step><para>Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! -</para></step> - -<step><para>Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.<footnote><para>To be strictly -accurate, <command>cc</> converts the source code into its own, -machine-independent <firstterm>p-code</> instead of assembly language -at this stage.</para></footnote></para></step> - -<step><para>Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here.</para></step> - -<step><para>Check that you have used things like functions and global -variables in a consistent way. For example, if you have called a -non-existent function, it will complain.</para></step> - -<step><para>If you are trying to produce an executable from several -source code files, work out how to fit them all together.</para></step> - -<step><para>Work out how to produce something that the system's run-time -loader will be able to load into memory and run.</para></step> - -<step><para>Finally, write the executable on the file -system.</para></step> - -</procedure> - -<para>The word <firstterm>compiling</> is often used to refer to just -steps 1 to 4—the others are referred to as -<firstterm>linking</>. Sometimes step 1 is referred to as -<firstterm>pre-processing</> and steps 3-4 as -<firstterm>assembling</>.</para> - -<para>Fortunately, almost all this detail is hidden from you, as -<command>cc</> is a front end that manages calling all these programs -with the right arguments for you; simply typing -<screen>$ <userinput>cc foobar.c</></screen></para> - -<para>will cause <filename>foobar.c</> to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -<screen>$ <userinput>cc foo.c bar.c</></screen> -</para> - -<para>Note that the syntax checking is just that—checking the -syntax. It will not check for any logical mistakes you may have made, -like putting the program into an infinite loop, or using a bubble -sort when you meant to use a binary sort.<footnote><para>In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't.</para></footnote></para> - -<para>There are lots and lots of options for <command>cc</>, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them.</para> - -<variablelist> -<varlistentry><term><option>-o <replaceable>filename</replaceable></></term> - -<listitem><para>The output name of the file. If you do not use this -option, <command>cc</> will produce an executable called -<filename>a.out</>.<footnote><para>The reasons for this are buried in -the mists of history.</para></footnote></para> - -<informalexample> -<screen>$ <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -$ <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></></screen> -</informalexample> -</listitem> -</varlistentry> - -<varlistentry><term><option>-c</option></term> -<listitem><para>Just compile the file, do not link it. Useful for toy -programs where you just want to check the syntax, or if you are using -a <filename>Makefile</filename>.</para> - -<informalexample> -<screen>$ <userinput>cc -c foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an <firstterm>object file</> (not an -executable) called <filename>foobar.o</filename>. This can be linked -together with other object files into an executable.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><option>-g</option></term> - -<listitem><para>Create a debug version of the executable. This makes -the compiler put information into the executable about which line of -which source file corresponds to which function call. A debugger can -use this information to show the source code as you step through the -program, which is <emphasis>very</emphasis> useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with <option>-g</option> while you are -developing a program and then compile a <quote>release -version</quote> without <option>-g</option> when you're satisfied it -works properly.</para> - -<informalexample> -<screen>$ <userinput>cc -g foobar.c</userinput></screen> -</informalexample> - -<para>This will produce a debug version of the -program.<footnote><para>Note, we didn't use the <option>-o</option> -flag to specify the executable name, so we will get an executable -called <filename>a.out</filename>. Producing a debug version called -<filename>foobar</filename> is left as an exercise for the -reader!</para></footnote></para> - -</listitem> -</varlistentry> - -<varlistentry><term><option>-O</option></term> - -<listitem><para>Create an optimised version of the executable. The -compiler performs various clever tricks to try and produce an -executable that runs faster than normal. You can add a number after -the <option>-O</option> to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of <command>cc</command> that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the -<option>-O2</option> option in some circumstances.</para> - -<para>Optimisation is usually only turned on when compiling a release -version.</para> - -<informalexample> -<screen>$ <userinput>cc -O -o foobar foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an optimised version of -<filename>foobar</filename>.</para> - -</listitem> -</varlistentry> -</variablelist> - -<para>The following three flags will force <command>cc</command> to -check that your code complies to the relevant international standard, -often referred to as the <acronym>ANSI</acronym> standard, though -strictly speaking it is an <acronym>ISO</acronym> standard.</para> - -<variablelist> - -<varlistentry><term><option>-Wall</option></term> - -<listitem><para>Enable all the warnings which the authors of -<command>cc</command> believe are worthwhile. Despite the name, it -will not enable all the warnings <command>cc</command> is capable -of.</para></listitem> - -</varlistentry> - -<varlistentry><term><option>-ansi</option></term> - -<listitem> -<para>Turn off most, but not all, of the non-<acronym>ANSI</> C -features provided by <command>cc</command>. Despite the name, it does -not guarantee strictly that your code will comply to the -standard.</para> -</listitem> - -</varlistentry> - -<varlistentry><term><option>-pedantic</option></term> - -<listitem> -<para>Turn off <emphasis>all</emphasis> -<command>cc</command>'s non-<acronym>ANSI</> C features.</para> -</listitem> - -</varlistentry> -</variablelist> - -<para>Without these flags, <command>cc</command> will allow you to -use some of its non-standard extensions to the standard. Some of -these are very useful, but will not work with other compilers—in -fact, one of the main aims of the standard is to allow people to -write code that will work with any compiler on any system. This is -known as <firstterm>portable code</firstterm>.</para> - -<para>Generally, you should try to make your code as portable as -possible, as otherwise you may have to completely re-write the -program later to get it to work somewhere else—and who knows -what you may be using in a few years time?</para> - -<informalexample> -<screen>$ <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an executable <filename>foobar</filename> -after checking <filename>foobar.c</filename> for standard -compliance.</para> - -<variablelist> - -<varlistentry><term><option>-l<replaceable>library</replaceable></option></term> - -<listitem><para>Specify a function library to be used during when -linking.</para> - -<para>The most common example of this is when compiling a program that -uses some of the mathematical functions in C. Unlike most other -platforms, these are in a separate library from the standard C one -and you have to tell the compiler to add it.</para> - -<para>The rule is that if the library is called -<filename>lib<replaceable>something</replaceable>.a</filename>, you -give <command>cc</command> the argument -<option>-l<replaceable>something</replaceable></option>. For example, -the math library is <filename>libm.a</filename>, so you give -<command>cc</command> the argument <option>-lm</option>. A common -<quote>gotcha</quote> with the math library is that it has to be the -last library on the command line.</para> - -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c -lm</userinput></screen> -</informalexample> - -<para>This will link the math library functions into -<filename>foobar</filename>.</para> - -<para>If you are compiling C++ code, you need to add -<option>-lg++</option>, or <option>-lstdc++</option> if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run <command>c++</command> -instead of <command>cc</command>, which does this for you. -<command>c++</command> can also be invoked as <command>g++</command> -on FreeBSD.</para> - -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -$ <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -$ <userinput>c++ -o foobar foobar.cc</userinput></screen> -</informalexample> - -<para>Each of these will both produce an executable -<filename>foobar</filename> from the C++ source file -<filename>foobar.cc</filename>. Note that, on Unix systems, C++ -source files traditionally end in <filename>.C</filename>, -<filename>.cxx</filename> or <filename>.cc</filename>, rather than -the <trademark>MS-DOS</trademark> style <filename>.cpp</filename> -(which was already used for something else). <command>gcc</command> -used to rely on this to work out what kind of compiler to use on the -source file; however, this restriction no longer applies, so you may -now call your C++ files <filename>.cpp</filename> with -impunity!</para> - -</listitem> -</varlistentry> -</variablelist> - -<sect1> -<title>Common <command>cc</command> Queries and Problems</title> - -<para>Q. I am trying to write a program which uses the -<function>sin()</function> function and I get an error like this. -What does it mean? -<informalexample> -<screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment</screen> -</informalexample> -</para> - -<para>A. When using mathematical functions like -<function>sin()</function>, you have to tell <command>cc</command> to -link in the math library, like so: -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c -lm</userinput></screen> -</informalexample></para> - -<para>Q. All right, I wrote this simple program to practice using -<option>-lm</option>. All it does is raise 2.1 to the power of 6. -<informalexample> -<programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -}</programlisting> -</informalexample> -and I compiled it as: -<informalexample> -<screen>$ <userinput>cc temp.c -lm</userinput></screen> -</informalexample> -like you said I should, but I get this when I run it: -<informalexample> -<screen>$ <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000</screen> -</informalexample> -</para> - -<para>This is <emphasis>not</emphasis> the right answer! What is -going on?</para> - -<para>A. When the compiler sees you call a function, it checks if it -has already seen a prototype for it. If it has not, it assumes the -function returns an <type>int</type>, which is -definitely not what you want here.</para> - -<para>Q. So how do I fix this?</para> - -<para>A. The prototypes for the mathematical functions are in -<filename>math.h</filename>. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! -<informalexample> -<programlisting>#include <math.h> -#include <stdio.h> - -int main() { -...</programlisting> -</informalexample> -</para> - -<para>After recompiling it as you did before, run it: -<informalexample> -<screen>$ <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121</screen> -</informalexample> -</para> - -<para>If you are using any of the mathematical functions, -<emphasis>always</emphasis> include <filename>math.h</filename> and -remember to link in the math library.</para> - -<para>Q. I compiled a file called <filename>foobar.c</filename> and I -cannot find an executable called <filename>foobar</filename>. Where's -it gone?</para> - -<para>A. Remember, <command>cc</command> will call the executable -<filename>a.out</filename> unless you tell it differently. Use the -<option>-o <replaceable>filename</replaceable></option> option: -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c</userinput></screen> -</informalexample> -</para> - -<para>Q. OK, I have an executable called <filename>foobar</filename>, -I can see it when I run <command>ls</command>, but when I type in -<command>foobar</command> at the command prompt it tells me there is -no such file. Why can it not find it?</para> - -<para>A. Unlike <trademark>MS-DOS</trademark>, Unix does not look in the -current directory when it is trying to find out which executable you -want it to run, unless you tell it to. Either type -<command>./foobar</command>, which means <quote>run the file called -<filename>foobar</filename> in the current directory</quote>, or -change your <systemitem class=environvar>PATH</systemitem> -environment variable so that it looks something like -<informalexample> -<screen>bin:/usr/bin:/usr/local/bin:.</screen> -</informalexample> -The dot at the end means <quote>look in the current directory if it is not in -any of the others</quote>.</para> - -<para>Q. I called my executable <filename>test</filename>, but -nothing happens when I run it. What is going on?</para> - -<para>A. Most Unix systems have a program called -<command>test</command> in <filename>/usr/bin</filename> and the -shell is picking that one up before it gets to checking the current -directory. Either type: -<informalexample> -<screen>$ <userinput>./test</userinput></screen> -</informalexample> -or choose a better name for your program!</para> - -<para>Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about <errorname>core -dumped</errorname>. What does that mean?</para> - -<para>A. The name <firstterm>core dump</firstterm> dates back to the -very early days of Unix, when the machines used core memory for -storing data. Basically, if the program failed under certain -conditions, the system would write the contents of core memory to -disk in a file called <filename>core</filename>, which the programmer -could then pore over to find out what went wrong.</para> - -<para>Q. Fascinating stuff, but what I am supposed to do now?</para> - -<para>A. Use <command>gdb</command> to analyse the core (see <xref -linkend="debugging">).</para> - -<para>Q. When my program dumped core, it said something about a -<errorname>segmentation fault</errorname>. What's that?</para> - -<para>A. This basically means that your program tried to perform some sort -of illegal operation on memory; Unix is designed to protect the -operating system and other programs from rogue programs.</para> - -<para>Common causes for this are: -<itemizedlist> -<listitem><para>Trying to write to a <symbol>NULL</symbol> pointer, eg -<programlisting>char *foo = NULL; -strcpy(foo, "bang!");</programlisting> -</para></listitem> - -<listitem><para>Using a pointer that hasn't been initialised, eg -<programlisting>char *foo; -strcpy(foo, "bang!");</programlisting> -The pointer will have some random value that, with luck, -will point into an area of memory that isn't available to -your program and the kernel will kill your program before -it can do any damage. If you're unlucky, it'll point -somewhere inside your own program and corrupt one of your -data structures, causing the program to fail -mysteriously.</para></listitem> - -<listitem><para>Trying to access past the end of an array, eg -<programlisting>int bar[20]; -bar[27] = 6;</programlisting></para></listitem> - -<listitem><para> Trying to store something in read-only memory, eg -<programlisting>char *foo = "My string"; -strcpy(foo, "bang!");</programlisting> -Unix compilers often put string literals like -<literal>"My string"</literal> into -read-only areas of memory.</para></listitem> - -<listitem><para>Doing naughty things with -<function>malloc()</function> and <function>free()</function>, eg -<programlisting>char bar[80]; -free(bar);</programlisting> -or -<programlisting>char *foo = malloc(27); -free(foo); -free(foo);</programlisting> -</para></listitem> - -</itemizedlist></para> - -<para>Making one of these mistakes will not always lead to an -error, but they are always bad practice. Some systems and -compilers are more tolerant than others, which is why programs -that ran well on one system can crash when you try them on an -another.</para> - -<para>Q. Sometimes when I get a core dump it says <errorname>bus -error</errorname>. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true?</para> - -<para>A. No, fortunately not (unless of course you really do have a hardware -problem…). This is usually another way of saying that you -accessed memory in a way you shouldn't have.</para> - -<para>Q. This dumping core business sounds as though it could be quite -useful, if I can make it happen when I want to. Can I do this, or -do I have to wait until there's an error?</para> - -<para>A. Yes, just go to another console or xterm, do -<screen>$ <userinput>ps</userinput></screen> -to find out the process ID of your program, and do -<screen>$ <userinput>kill -ABRT <replaceable>pid</replaceable></userinput></screen> -where <parameter><replaceable>pid</replaceable></parameter> is the -process ID you looked up.</para> - -<para>This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -<symbol>SIGABRT</symbol>, there are several other signals which have -a similar effect.</para> - -</sect1> -</chapter> - - -<chapter> -<title>Make</title> - -<sect1> -<title>What is <command>make</command>?</title> - -<para>When you're working on a simple program with only one or two source -files, typing in -<screen>$ <userinput>cc file1.c file2.c</userinput></screen> -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too.</para> - -<para>One way to get around this is to use object files and only recompile -the source file if the source code has changed. So we could have -something like: -<screen>$ <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip</screen> -if we'd changed <filename>file37.c</filename>, but not any of the -others, since the last time we compiled. This may speed up the -compilation quite a bit, but doesn't solve the typing -problem.</para> - -<para>Or we could write a shell script to solve the typing problem, but it -would have to re-compile everything, making it very inefficient on a -large project.</para> - -<para>What happens if we have hundreds of source files lying about? What if -we're working in a team with other people who forget to tell us when -they've changed one of their source files that we use?</para> - -<para>Perhaps we could put the two solutions together and write something -like a shell script that would contain some kind of magic rule saying -when a source file needs compiling. Now all we need now is a program -that can understand these rules, as it's a bit too complicated for the -shell.</para> - -<para>This program is called <command>make</command>. It reads in a -file, called a <firstterm>makefile</firstterm>, that tells it how -different files depend on each other, and works out which files need -to be re-compiled and which ones don't. For example, a rule could say -something like <quote>if <filename>fromboz.o</filename> is older than -<filename>fromboz.c</filename>, that means someone must have changed -<filename>fromboz.c</filename>, so it needs to be -re-compiled.</quote> The makefile also has rules telling make -<emphasis>how</emphasis> to re-compile the source file, making it a -much more powerful tool.</para> - -<para>Makefiles are typically kept in the same directory as the -source they apply to, and can be called -<filename>makefile</filename>, <filename>Makefile</filename> or -<filename>MAKEFILE</filename>. Most programmers use the name -<filename>Makefile</filename>, as this puts it near the top of a -directory listing, where it can easily be seen.<footnote><para>They -don't use the <filename>MAKEFILE</filename> form as block capitals -are often used for documentation files like -<filename>README</filename>.</para></footnote></para> - -</sect1> - -<sect1> -<title>Example of using <command>make</command></title> - -<para>Here's a very simple make file: -<programlisting>foo: foo.c - cc -o foo foo.c</programlisting> -It consists of two lines, a dependency line and a creation line.</para> - -<para>The dependency line here consists of the name of the program -(known as the <firstterm>target</firstterm>), followed by a colon, -then whitespace, then the name of the source file. When -<command>make</command> reads this line, it looks to see if -<filename>foo</filename> exists; if it exists, it compares the time -<filename>foo</filename> was last modified to the time -<filename>foo.c</filename> was last modified. If -<filename>foo</filename> does not exist, or is older than -<filename>foo.c</filename>, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when <filename>foo.c</filename> needs to be re-compiled.</para> - -<para>The creation line starts with a <token>tab</token> (press the -<keycap>tab</keycap> key) and then the command you would type to -create <filename>foo</filename> if you were doing it at a command -prompt. If <filename>foo</filename> is out of date, or does not -exist, <command>make</command> then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile <filename>foo.c</filename>.</para> - -<para>So, when you type <userinput>make</userinput>, it will make -sure that <filename>foo</filename> is up to date with respect to your -latest changes to <filename>foo.c</filename>. This principle can be -extended to <filename>Makefile</filename>s with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing <userinput>make -world</userinput> in the appropriate directory!</para> - -<para>Another useful property of makefiles is that the targets don't have -to be programs. For instance, we could have a make file that looks -like this: -<programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me</programlisting></para> - -<para>We can tell make which target we want to make by typing: -<screen>$ <userinput>make <replaceable>target</replaceable></userinput></screen> -<command>make</command> will then only look at that target and ignore any -others. For example, if we type <userinput>make foo</userinput> with the -makefile above, make will ignore the <action>install</action> target.</para> - -<para>If we just type <userinput>make</userinput> on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed <userinput>make</userinput> here, it will -just go to the <action>foo</action> target, re-compile -<filename>foo</filename> if necessary, and then stop without going on -to the <action>install</action> target.</para> - -<para>Notice that the <action>install</action> target doesn't -actually depend on anything! This means that the command on the -following line is always executed when we try to make that target by -typing <userinput>make install</userinput>. In this case, it will -copy <filename>foo</filename> into the user's home directory. This is -often used by application makefiles, so that the application can be -installed in the correct directory when it has been correctly -compiled.</para> - -<para>This is a slightly confusing subject to try and explain. If you -don't quite understand how <command>make</command> works, the best -thing to do is to write a simple program like <quote>hello -world</quote> and a make file like the one above and experiment. Then -progress to using more than one source file, or having the source -file include a header file. The <command>touch</command> command is -very useful here—it changes the date on a file without you -having to edit it.</para> - -</sect1> - -<sect1> -<title>FreeBSD Makefiles</title> - -<para>Makefiles can be rather complicated to write. Fortunately, -BSD-based systems like FreeBSD come with some very powerful ones as -part of the system. One very good example of this is the FreeBSD -ports system. Here's the essential part of a typical ports -<filename>Makefile</filename>: -<programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk></programlisting></para> - -<para>Now, if we go to the directory for this port and type -<userinput>make</userinput>, the following happens:</para> - -<procedure> -<step><para>A check is made to see if the source code for this port is -already on the system.</para></step> - -<step><para>If it isn't, an FTP connection to the URL in -<symbol>MASTER_SITES</symbol> is set up to download the -source.</para></step> - -<step><para>The checksum for the source is calculated and compared it with -one for a known, good, copy of the source. This is to make sure that -the source was not corrupted while in transit.</para></step> - -<step><para>Any changes required to make the source work on FreeBSD are -applied—this is known as <firstterm>patching</firstterm>.</para></step> - -<step><para>Any special configuration needed for the source is done. -(Many Unix program distributions try to work out which version of -Unix they are being compiled on and which optional Unix features are -present—this is where they are given the information in the -FreeBSD ports scenario).</para></step> - -<step><para>The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -<command>make</command>—the program's own make file has the -necessary information to build the program.</para></step> - -<step><para>We now have a compiled version of the program. If we -wish, we can test it now; when we feel confident about the program, -we can type <userinput>make install</userinput>. This will cause the -program and any supporting files it needs to be copied into the -correct location; an entry is also made into a <database>package -database</database>, so that the port can easily be uninstalled later -if we change our mind about it.</para></step> - -</procedure> - -<para>Now I think you'll agree that's rather impressive for a four -line script!</para> - -<para>The secret lies in the last line, which tells -<command>make</command> to look in the system makefile called -<filename>bsd.port.mk</filename>. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells <command>make</command> to do all the -things above (plus a couple of other things I didn't mention, -including handling any errors that may occur) and anyone can get -access to that just by putting a single line in their own make -file!</para> - -<para>If you want to have a look at these system makefiles, they're -in <filename>/usr/share/mk</filename>, but it's probably best to wait -until you've had a bit of practice with makefiles, as they are very -complicated (and if you do look at them, make sure you have a flask -of strong coffee handy!)</para> - -</sect1> - -<sect1> -<title>More advanced uses of <command>make</command></title> - -<para><command>Make</command> is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of <command>make</command>, and they all -differ considerably. The best way to learn what they can do is -probably to read the documentation—hopefully this introduction will -have given you a base from which you can do this.</para> - -<para>The version of make that comes with FreeBSD is the <application>Berkeley -make</application>; there is a tutorial for it in -<filename>/usr/share/doc/psd/12.make</filename>. To view it, do -<screen>$ <userinput>zmore paper.ascii.gz</userinput></screen> -in that directory.</para> - -<para>Many applications in the ports use <application>GNU -make</application>, which has a very good set of <quote>info</quote> -pages. If you have installed any of these ports, <application>GNU -make</application> will automatically have been installed as -<command>gmake</command>. It's also available as a port and package -in its own right.</para> - -<para>To view the info pages for <application>GNU make</application>, -you will have to edit the <filename>dir</filename> file in the -<filename>/usr/local/info</filename> directory to add an entry for -it. This involves adding a line like -<programlisting> * Make: (make). The GNU Make utility.</programlisting> -to the file. Once you have done this, you can type -<userinput>info</userinput> and then select -<guimenuitem>make</guimenuitem> from the menu (or in -<application>Emacs</application>, do <userinput>C-h -i</userinput>).</para> - -</sect1> -</chapter> - -<chapter id="debugging"> -<title>Debugging</title> - -<sect1> -<title>The Debugger</title> - -<para>The debugger that comes with FreeBSD is called -<command>gdb</command> (<application>GNU -debugger</application>). You start it up by typing -<screen>$ <userinput>gdb <replaceable>progname</replaceable></userinput></screen> -although most people prefer to run it inside -<application>Emacs</application>. You can do this by: -<screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen></para> - -<para>Using a debugger allows you to run the program under more -controlled circumstances. Typically, you can step through the program -a line at a time, inspect the value of variables, change them, tell -the debugger to run up to a certain point and then stop, and so on. -You can even attach to a program that's already running, or load a -core file to investigate why the program crashed. It's even possible -to debug the kernel, though that's a little trickier than the user -applications we'll be discussing in this section.</para> - -<para><command>gdb</command> has quite good on-line help, as well as -a set of info pages, so this section will concentrate on a few of the -basic commands.</para> - -<para>Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it <ulink -URL="../../ports/devel.html">xxgdb</ulink> -in the ports collection.</para> - -<para>This section is intended to be an introduction to using -<command>gdb</command> and does not cover specialised topics such as -debugging the kernel.</para> - -</sect1> - -<sect1> -<title>Running a program in the debugger</title> - -<para>You'll need to have compiled the program with the -<option>-g</option> option to get the most out of using -<command>gdb</command>. It will work without, but you'll only see the -name of the function you're in, instead of the source code. If you -see a line like: -<screen>… (no debugging symbols found) …</screen>when -<command>gdb</command> starts up, you'll know that the program wasn't -compiled with the <option>-g</option> option.</para> - -<para>At the <command>gdb</command> prompt, type <userinput>break -main</userinput>. This will tell the debugger to skip over the -preliminary set-up code in the program and start at the beginning of -your code. Now type <userinput>run</userinput> to start the -program—it will start at the beginning of the set-up code and -then get stopped by the debugger when it calls -<function>main()</function>. (If you've ever wondered where -<function>main()</function> gets called from, now you know!).</para> - -<para>You can now step through the program, a line at a time, by -pressing <command>n</command>. If you get to a function call, you can -step into it by pressing <command>s</command>. Once you're in a -function call, you can return from stepping into a function call by -pressing <command>f</command>. You can also use <command>up</command> and -<command>down</command> to take a quick look at the caller.</para> - -<para>Here's a simple example of how to spot a mistake in a program -with <command>gdb</command>. This is our program (with a deliberate -mistake): -<programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -}</programlisting> -</para> - -<para>This program sets <symbol>i</symbol> to be <literal>5</literal> -and passes it to a function <function>bazz()</function> which prints -out the number we gave it.</para> - -<para>When we compile and run the program we get -<screen>$ <userinput>cc -g -o temp temp.c</userinput> -$ <userinput>./temp</userinput> -This is my program -anint = 4231</screen></para> - -<para>That wasn't what we expected! Time to see what's going -on!<screen>$ <userinput>gdb temp</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb)</screen></para> - - -<para>Hang on a minute! How did <symbol>anint</symbol> get to be -<literal>4231</literal>? Didn't we set it to be <literal>5</literal> -in <function>main()</function>? Let's move up to -<function>main()</function> and have a look.</para> - -<para><screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></></screen> -Oh dear! Looking at the code, we forgot to initialise -<symbol>i</symbol>. We meant to put -<programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</></programlisting> -but we left the <literal>i=5;</literal> line out. As we didn't -initialise <symbol>i</symbol>, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be <literal>4231</literal>.</para> - -<note><para><command>gdb</command> displays the stack frame -every time we go into or out of a function, even if we're using -<command>up</command> and <command>down</command> to move around the -call stack. This shows the name of the function and the values of -its arguments, which helps us keep track of where we are and what's -going on. (The stack is a storage area where the program stores -information about the arguments passed to functions and where to go -when it returns from a function call).</para></note> - -</sect1> - -<sect1> -<title>Examining a core file</title> - -<para>A core file is basically a file which contains the complete -state of the process when it crashed. In <quote>the good old -days</quote>, programmers had to print out hex listings of core files -and sweat over machine code manuals, but now life is a bit easier. -Incidentally, under FreeBSD and other 4.4BSD systems, a core file is -called <filename><replaceable>progname</>.core</> instead of just -<filename>core</filename>, to make it clearer which program a core -file belongs to.</para> - -<para>To examine a core file, start up <command>gdb</command> in the -usual way. Instead of typing <command>break</command> or -<command>run</command>, type -<screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen> -If you're not in the same directory as the core file, you'll have to -do <userinput>dir /path/to/core/file</userinput> first.</para> - -<para>You should see something like this: -<screen>$ <userinput>gdb a.out</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb)</screen></para> - -<para>In this case, the program was called -<filename>a.out</filename>, so the core file is called -<filename>a.out.core</filename>. We can see that the program crashed -due to trying to access an area in memory that was not available to -it in a function called <function>bazz</function>.</para> - -<para>Sometimes it's useful to be able to see how a function was -called, as the problem could have occurred a long way up the call -stack in a complex program. The <command>bt</command> command causes -<command>gdb</command> to print out a back-trace of the call -stack: -<screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)</screen>The <function>end()</function> function is called when -a program crashes; in this case, the <function>bazz()</function> -function was called from <function>main()</function>.</para> - -</sect1> - -<sect1> -<title>Attaching to a running program</title> - -<para>One of the neatest features about <command>gdb</command> is -that it can attach to a program that's already running. Of course, -that assumes you have sufficient permissions to do so. A common -problem is when you are stepping through a program that forks, and -you want to trace the child, but the debugger will only let you trace -the parent.</para> - -<para>What you do is start up another <command>gdb</command>, use -<command>ps</command> to find the process ID for the child, and -do<screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen> -in <command>gdb</command>, and then debug as usual.</para> - -<para><quote>That's all very well,</quote> you're probably thinking, -<quote>but by the time I've done that, the child process will be over -the hill and far away</quote>. Fear not, gentle reader, here's how to -do it (courtesy of the <command>gdb</command> info pages): -<screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation></screen> -Now all you have to do is attach to the child, set -<symbol>PauseMode</symbol> to <literal>0</literal>, and -wait for the <function>sleep()</function> call to return!</para> - -</sect1> -</chapter> - -<chapter id="emacs"> -<title>Using Emacs as a Development Environment</title> - -<sect1> -<title>Emacs</title> - -<para>Unfortunately, Unix systems don't come with the kind of -everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package -integrated development environments that other systems -have.<footnote><para>At least, not unless you pay out very large sums -of money.</para></footnote> However, it is possible to set up your -own environment. It may not be as pretty, and it may not be quite as -integrated, but you can set it up the way you want it. And it's free. -And you have the source to it.</para> - -<para>The key to it all is Emacs. Now there are some people who -loathe it, but many who love it. If you're one of the former, I'm -afraid this section will hold little of interest to you. Also, you'll -need a fair amount of memory to run it—I'd recommend 8MB in -text mode and 16MB in X as the bare minimum to get reasonable -performance.</para> - -<para>Emacs is basically a highly customisable editor—indeed, -it has been customised to the point where it's more like an operating -system than an editor! Many developers and sysadmins do in fact -spend practically all their time working inside Emacs, leaving it -only to log out.</para> - -<para>It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: -<itemizedlist> - -<listitem><para>Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc.</para></listitem> - -<listitem><para>Pull-down menus and online help.</para></listitem> - -<listitem><para>Language-dependent syntax highlighting and -indentation.</para></listitem> - -<listitem><para>Completely customisable.</para></listitem> - -<listitem><para>You can compile and debug programs within -Emacs.</para></listitem> - -<listitem><para>On a compilation error, you can jump to the offending -line of source code.</para></listitem> - -<listitem><para>Friendly-ish front-end to the <command>info</command> -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself.</para></listitem> - -<listitem><para>Friendly front-end to <command>gdb</command>, -allowing you to look at the source code as you step through your -program.</para></listitem> - -<listitem><para>You can read Usenet news and mail while your program -is compiling.</para></listitem> - -</itemizedlist>And doubtless many more that I've overlooked.</para> - -<para>Emacs can be installed on FreeBSD using <ulink -URL="../../ports/editors.html">the Emacs -port</ulink>.</para> - -<para>Once it's installed, start it up and do <userinput>C-h -t</userinput> to read an Emacs tutorial—that means hold down -the <keycap>control</keycap> key, press <keycap>h</keycap>, let go of -the <keycap>control</keycap> key, and then press <keycap>t</keycap>. -(Alternatively, you can you use the mouse to select <guimenuitem>Emacs -Tutorial</guimenuitem> from the <guimenu>Help</guimenu> menu).</para> - -<para>Although Emacs does have menus, it's well worth learning the -key bindings, as it's much quicker when you're editing something to -press a couple of keys than to try and find the mouse and then click -on the right place. And, when you're talking to seasoned Emacs users, -you'll find they often casually throw around expressions like -<quote><literal>M-x replace-s RET foo RET bar RET</literal></quote> -so it's useful to know what they mean. And in any case, Emacs has far -too many useful functions for them to all fit on the menu -bars.</para> - -<para>Fortunately, it's quite easy to pick up the key-bindings, as -they're displayed next to the menu item. My advice is to use the -menu item for, say, opening a file until you understand how it works -and feel confident with it, then try doing C-x C-f. When you're happy -with that, move on to another menu command.</para> - -<para>If you can't remember what a particular combination of keys -does, select <guimenuitem>Describe Key</guimenuitem> from the -<guimenu>Help</guimenu> menu and type it in—Emacs will tell you -what it does. You can also use the <guimenuitem>Command -Apropos</guimenuitem> menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it.</para> - -<para>By the way, the expression above means hold down the -<keysym>Meta</keysym> key, press <keysym>x</keysym>, release the -<keysym>Meta</keysym> key, type <userinput>replace-s</userinput> -(short for <literal>replace-string</literal>—another feature of -Emacs is that you can abbreviate commands), press the -<keysym>return</keysym> key, type <userinput>foo</userinput> (the -string you want replaced), press the <keysym>return</keysym> key, -type bar (the string you want to replace <literal>foo</literal> with) -and press <keysym>return</keysym> again. Emacs will then do the -search-and-replace operation you've just requested.</para> - -<para>If you're wondering what on earth the <keysym>Meta</keysym> key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -<keycap>alt</keycap> key (or if you're unlucky, the <keysym>escape</keysym> -key).</para> - -<para>Oh, and to get out of Emacs, do <command>C-x C-c</command> -(that means hold down the <keysym>control</keysym> key, press -<keysym>c</keysym>, press <keysym>x</keysym> and release the -<keysym>control</keysym> key). If you have any unsaved files open, -Emacs will ask you if you want to save them. (Ignore the bit in the -documentation where it says <command>C-z</command> is the usual way -to leave Emacs—that leaves Emacs hanging around in the -background, and is only really useful if you're on a system which -doesn't have virtual terminals).</para> - -</sect1> - -<sect1> -<title>Configuring Emacs</title> - -<para>Emacs does many wonderful things; some of them are built in, -some of them need to be configured.</para> - -<para>Instead of using a proprietary macro language for -configuration, Emacs uses a version of Lisp specially adapted for -editors, known as Emacs Lisp. This can be quite useful if you want to -go on and learn something like Common Lisp, as it's considerably -smaller than Common Lisp (although still quite big!).</para> - -<para>The best way to learn Emacs Lisp is to download the <ulink -URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs -Tutorial</ulink></para> - -<para>However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -<filename>.emacs</filename> file, which should be enough to get you -started. Just copy it into your home directory and restart Emacs if -it's already running; it will read the commands from the file and -(hopefully) give you a useful basic setup.</para> - -</sect1> - -<sect1> -<title>A sample <filename>.emacs</filename> file</title> - -<para>Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning.</para> - -<para> -<itemizedlist> - -<listitem><para>Everything beginning with a <literal>;</> is a -comment and is ignored by Emacs.</para></listitem> - -<listitem><para>In the first line, the -<literal>-*- Emacs-Lisp -*-</literal> is so that we can -edit the <filename>.emacs</filename> file itself within Emacs and get -all the fancy features for editing Emacs Lisp. Emacs usually tries to -guess this based on the filename, and may not get it right for -<filename>.emacs</filename>. </para></listitem> - -<listitem><para>The <keysym>tab</keysym> key is bound to an -indentation function in some modes, so when you press the tab key, it -will indent the current line of code. If you want to put a -<token>tab</token> character in whatever you're writing, hold the -<keysym>control</keysym> key down while you're pressing the -<keysym>tab</keysym> key.</para></listitem> - -<listitem><para>This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename.</para></listitem> - -<listitem><para>Emacs already has a pre-defined function called -<function>next-error</function>. In a compilation output window, this -allows you to move from one compilation error to the next by doing -<command>M-n</command>; we define a complementary function, -<function>previous-error</function>, that allows you to go to a -previous error by doing <command>M-p</command>. The nicest feature of -all is that <command>C-c C-c</command> will open up the source file -in which the error occurred and jump to the appropriate -line.</para></listitem> - -<listitem><para> We enable Emacs's ability to act as a server, so -that if you're doing something outside Emacs and you want to edit a -file, you can just type in -<screen>$ <userinput>emacsclient <replaceable>filename</replaceable></userinput></screen> -and then you can edit the file in your Emacs!<footnote><para>Many -Emacs users set their <systemitem -class=environvar>EDITOR</systemitem> environment to -<literal>emacsclient</literal> so this happens every time they need -to edit a file.</para></footnote></para></listitem> - -</itemizedlist> -</para> - -<example> -<title>A sample <filename>.emacs</filename> file</title> -<screen>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") </screen> - -<screen>(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n)))</screen> - -<screen>;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") -</screen> -</example> - -</sect1> - -<sect1> -<title>Extending the Range of Languages Emacs Understands</title> - -<para>Now, this is all very well if you only want to program in the -languages already catered for in the <filename>.emacs</filename> file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called <quote>whizbang</quote> comes out, full of exciting -features?</para> - -<para>The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in <filename>.el</filename>, short for <quote>Emacs -Lisp</quote>. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -<screen>$ <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput></screen> -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -<filename>/usr/local/share/emacs/site-lisp</filename>.</para> - -<para>So for example, if the output from the find command was -<screen>/usr/ports/lang/whizbang/work/misc/whizbang.el</screen> -we would do -<screen>$ <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput></screen> -</para> - -<para>Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -<filename>.wiz</filename>. We need to add an entry to our -<filename>.emacs</filename> file to make sure Emacs will be able to -use the information in <filename>whizbang.el</filename>.</para> - -<para>Find the <symbol>auto-mode-alist entry</symbol> in -<filename>.emacs</filename> and add a line for whizbang, such -as: -<programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</></programlisting> -This means that Emacs will automatically go into -<function>whizbang-mode</function> when you edit a file ending in -<filename>.wiz</filename>.</para> - -<para>Just below this, you'll find the -<symbol>font-lock-auto-mode-list</symbol> entry. Add -<function>whizbang-mode</function> to it like so: -<programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode")</programlisting> -This means that Emacs will always enable -<function>font-lock-mode</function> (ie syntax highlighting) when -editing a <filename>.wiz</filename> file.</para> - -<para>And that's all that's needed. If there's anything else you want -done automatically when you open up a <filename>.wiz</filename> file, -you can add a <function>whizbang-mode hook</function> (see -<function>my-scheme-mode-hook</function> for a simple example that -adds <function>auto-indent</function>).</para> - -</sect1> -</chapter> - -<chapter> -<title>Further Reading</title> - -<itemizedlist> -<listitem><para>Brian Harvey and Matthew Wright -<emphasis>Simply Scheme</emphasis> -MIT 1994.<!-- <br> --> -ISBN 0-262-08226-8</para></listitem> - -<listitem><para>Randall Schwartz -<emphasis>Learning Perl</emphasis> -O'Reilly 1993<!-- <br> --> -ISBN 1-56592-042-2</para></listitem> - -<listitem><para>Patrick Henry Winston and Berthold Klaus Paul Horn -<emphasis>Lisp (3rd Edition)</emphasis> -Addison-Wesley 1989<!-- <br> --> -ISBN 0-201-08319-1</para></listitem> - -<listitem><para>Brian W. Kernighan and Rob Pike -<emphasis>The Unix Programming Environment</emphasis> -Prentice-Hall 1984<!-- <br> --> -ISBN 0-13-937681-X</para></listitem> - -<listitem><para>Brian W. Kernighan and Dennis M. Ritchie -<emphasis>The C Programming Language (2nd Edition)</emphasis> -Prentice-Hall 1988<!-- <br> --> -ISBN 0-13-110362-8</para></listitem> - -<listitem><para>Bjarne Stroustrup -<emphasis>The C++ Programming Language</emphasis> -Addison-Wesley 1991<!-- <br> --> -ISBN 0-201-53992-6</para></listitem> - -<listitem><para>W. Richard Stevens -<emphasis>Advanced Programming in the Unix Environment</emphasis> -Addison-Wesley 1992<!-- <br> --> -ISBN 0-201-56317-7</para></listitem> - -<listitem><para>W. Richard Stevens -<emphasis>Unix Network Programming</emphasis> -Prentice-Hall 1990<!-- <br> --> -ISBN 0-13-949876-1</para></listitem> - -</itemizedlist> - -</chapter> -</book> |