From 799d8c1a69e1218e588de1a2296f006048649fa3 Mon Sep 17 00:00:00 2001 From: John Fieber Date: Fri, 7 Jul 1995 22:25:55 +0000 Subject: [PATCH] Numerous changes by Jordan. Submitted by: Jordan Hubbard --- share/doc/handbook/handbook.sgml | 5 +- share/doc/handbook/history.sgml | 117 ++++++++++++++++------- share/doc/handbook/nutshell.sgml | 33 ++++--- share/doc/handbook/ports.sgml | 89 ++++++++---------- share/doc/handbook/submitters.sgml | 10 +- share/doc/handbook/sup.sgml | 4 +- share/doc/handbook/troubleshooting.sgml | 120 +----------------------- 7 files changed, 151 insertions(+), 227 deletions(-) diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml index 01fe1a8558d2..89bdc2d42196 100644 --- a/share/doc/handbook/handbook.sgml +++ b/share/doc/handbook/handbook.sgml @@ -1,4 +1,4 @@ - + The FreeBSD Documentation Project - June 30, 1995 + July 7, 1995 Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD Release @@ -84,7 +84,6 @@ OUTLINE: &nutshell; &history; &relnotes; - * FreeBSD now and in the future &install; &basics; diff --git a/share/doc/handbook/history.sgml b/share/doc/handbook/history.sgml index 55b96b114e2d..437d20be0827 100644 --- a/share/doc/handbook/history.sgml +++ b/share/doc/handbook/history.sgml @@ -1,44 +1,95 @@ - + -A brief history of FreeBSD +A brief history of FreeBSD, according to Jordan Hubbard

Contributed by &a.jkh;. -The FreeBSD project was started somewhere in the early part of 1992 as -an outgrowth of the "Unofficial 386BSD Patchkit" by the patchkit's -last 3 coordinators: Nate Williams, Jordan Hubbard and Rod Grimes. +The FreeBSD project had its genesis in the early part of 1992, +partially as an outgrowth of the "Unofficial 386BSD Patchkit" by the +patchkit's last 3 coordinators: Nate Williams, Rod Grimes and myself. David Greenman and Julian Elischer were also lurking in the background around this time, though they didn't come fully into the project until -a month or two after it was more or less officially launched. The -original working title of the project was also "386BSD 0.5" or "386BSD -Interim", a reference to the fact that the original goal was to -produce an intermediate snapshot of 386BSD. +a month or two after it was more or less officially launched. Our +original goal was to produce an intermediate snapshot of 386BSD in +order to fix a number of problems with it that the patchkit mechanism +just wasn't capable of solving. Some of you may remember the early +working title for the project being "386BSD 0.5" or "386BSD Interim" +in reference to that fact. -386BSD was Bill Jolitz's operating system, which had been up to -that point suffering rather severely from neglect, a consequence -of which was to cause the patchkit to swell ever more -uncomfortably with each passing day. The 3 ex-patchkit -coordinators were all in agreement that the patchkit had to die. -It was rapidly outliving its usefulness, and it would be a far -easier thing to simply do another 386BSD release with all patches -applied and a number of its aging utilities updated. +386BSD was Bill Jolitz's operating system, which had been up to that +point suffering rather severely from almost a year's worth of neglect. +As the patchkit swelled ever more uncomfortably with each passing day, +we were in unanimous agreement that something had to be done and +decided to try and assist Bill by providing this interim "cleanup" +snapshot. Those plans came to a rude halt when Bill Jolitz suddenly +decided to withdraw his sanction from the project and without any +clear indication of what would be done instead (and it was, in fact, +to be another full year before he was even heard from in public +again!). -These plans came to a rude halt when Bill Jolitz suddenly decided -to withdraw his sanction from the project. It didn't take the -team members long to decide that the goal remained worthwhile -even without Bill's support, and so they adopted the name -"FreeBSD", which was coined by David Greenman. +It didn't take us long to decide that the goal remained worthwhile +even without Bill's support, and so we adopted the name "FreeBSD", +which was coined by David Greenman. Our initial objectives were set +after consulting with the system's current users and once it became +clear that the project was on the road to perhaps even becoming a +reality, I contacted Walnut Creek CDROM with an eye towards improving +FreeBSD's distribution channels to those many unfortunates without +easy access to the Internet. Walnut Creek CDROM not only supported +the idea of distributing FreeBSD on CD but went so far as to provide +the project with a machine to work on and a fast Internet connection. +Without Walnut Creek CDROM's almost unprecidented degree of faith in +what was, at the time, a completely unknown project, it is in fact +very unlikely that FreeBSD would have gotten as far, as fast, as it +has today. + +The first CDROM (and general net-wide) distribution was FreeBSD 1.0, +released in December of '93. This was based on the 4.3 BSD Lite +("Net/2") tape from U.C. Berkeley with many components provided by +386BSD and the Free Software Foundation. It was a fairly reasonable +success for a first offering, and we followed this release with the +highly successful FreeBSD 1.1 version in May of 1994. + +Around this time, some rather unexpected storm clouds formed on our +horizon as Novell and U.C. Berkeley settled their long-running lawsuit +over the legal status of the Berkeley Net/2 tape. A condition of that +settlement was U.C. Berkeley's concession that large parts of Net/2 +was "encumbered" code and property of Novell, who had in turn aquired +it from AT&T some time previously. What Berkeley got in return was +Novell's "blessing" that the 4.4 Lite release, when it was finally +released, would be declared unencumbered and all existing Net/2 users +would be strongly encouraged to switch. This included us, and we were +given until the end of July 1994 to stop shipping our own Net/2 based +product. Under the terms of that agreement, were were allowed one +last release before the deadline and that became FreeBSD 1.1.5.1, the +culmination of our year's work with Net/2 and generally considered by +many to be a significant project milestone for stability and general +performance.. + +We then set about the arduous task of literally re-inventing ourselves +with a completely new and rather incomplete set of 4.4 Lite bits. The +"Lite" releases were light in part because Berkeley's CSRG removed +large chunks of code required for actually making a bootable running +system out of it due to various legal requirements and the fact that +the Intel port of 4.4 was highly incomplete. It took us until +December of 1994 to make this transition, and in January of 1995 we +released FreeBSD 2.0 to the net and on CDROM. Despite being still +more than a little rough around the edges, the release was a +significant success and has since been followed by the more robust and +easier to install FreeBSD 2.0.5 release in June of 1995. + +Where to from here? Well, we intend to release FreeBSD 2.1 sometime +in September of 1995 and have reasonable expectations that it will +meet or exceed all of the standards for quality we set with FreeBSD +1.1.5.1 back in July of 1994. From there, we'll probably go to a +two-track scheme with a "stable" branch of FreeBSD and an +"experimental" branch, where development can continue at its usually +rapid pace without penalizing those who just want a stable, working +system without too much excitement. We also intend to focus on any +remaining areas of weakness, like documentation or missing drivers, +and steadily increase the overall quality and feature set of the +system well into 1996 and beyond. + + Jordan -Once it also became clear that the project was on the road to -perhaps even becoming a reality, Jordan Hubbard contacted Walnut -Creek CDROM with an eye towards improving FreeBSD's distribution -channels to those many unfortunates without easy access to the -Internet. Walnut Creek CDROM not only supported the idea of -distributing FreeBSD on CD, but went so far as to provide the -project with a machine to work on and a fast Internet connection. -Without Walnut Creek CDROM's almost unprecidented degree of faith -in what was, at the time, a completely unknown project, it is -very unlikely that FreeBSD would have gotten as far, as fast, as -it has today. diff --git a/share/doc/handbook/nutshell.sgml b/share/doc/handbook/nutshell.sgml index d2d330208422..2d7aae8a7bbc 100644 --- a/share/doc/handbook/nutshell.sgml +++ b/share/doc/handbook/nutshell.sgml @@ -1,4 +1,4 @@ - + FreeBSD in a nutshell @@ -31,7 +31,7 @@ as such from the ground up. The industry standard X Window System (X11R6) provides a graphical user interface (GUI) for the cost of a - common VGA card and monitor. + common VGA card and monitor and comes with full sources. Binary compatibility with many programs built for SCO, BSDI, NetBSD, and 386BSD. Hundreds of ready-to-run applications are @@ -52,9 +52,8 @@ and memory. A full compliment of C, C++ and Fortran development tools. Many additional - languages for research and advanced development are - available as well in the ports and packages - collection. + languages for advanced research and development are + also available in the ports and packages collection. Source code for the entire system means you have the greatest degree of control over your environment. Why be locked into a proprietary solution and at the mercy of your vendor @@ -71,19 +70,19 @@ many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. As many of the commercial giants struggle to - field PC operating systems with such features, performance, + field PC operating systems with such features, performance and reliability, FreeBSD can offer them now! The applications to which FreeBSD can be put are truly limited only by your own imagination. From software - development to factory automation. Inventory control to - azimuth correction of remote satellite antennae, if it can - be done with a commercial UNIX product, then it's more than + development to factory automation, inventory control to + azimuth correction of remote satellite antennae; if it can + be done with a commercial UNIX product then it's more than likely that you can do it with FreeBSD, too! FreeBSD also benefits significantly from the literally thousands of high quality applications developed by research centers and - universities around the world, and often available at low - (to no) cost. Commercial applications are also available + universities around the world, often available at little + to no cost. Commercial applications are also available and appearing in greater numbers every day. Because the source code for FreeBSD itself is generally @@ -112,7 +111,7 @@ Education: Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer - architecture and networks than the hands on, under the + architecture and networking than the hands on, under the hood experience that FreeBSD can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those who's @@ -124,22 +123,22 @@ computer science. FreeBSD's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about - special licensing agreements, or with limitations on what - may be discussed in certain forums. + special licensing agreements or limitations on what + may be discussed in open forums. Networking: Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? FreeBSD can easily turn that unused 386 or 486 PC sitting in the corner into an advanced router with sophisticated packet filtering capabilities. - X Window workstation: FreeBSD is an excellent + X Window workstation: FreeBSD is a fine choice for an inexpensive X terminal solution, either using the freely available XFree86 server or one of the excellent commercial servers provided by X Inside. Unlike an X terminal, FreeBSD allows many applications to be run locally, if desired, thus relieving the burden on a - central server. Additionally, FreeBSD can boot - "diskless" making individual workstations even cheaper + central server. FreeBSD can even boot + "diskless", making individual workstations even cheaper and easier to administer. Software Development: The basic FreeBSD system comes with a full compliment of development tools diff --git a/share/doc/handbook/ports.sgml b/share/doc/handbook/ports.sgml index ae5eeb198b8e..00b7ae3827c7 100644 --- a/share/doc/handbook/ports.sgml +++ b/share/doc/handbook/ports.sgml @@ -1,4 +1,4 @@ - + The Ports collection @@ -16,49 +16,58 @@ back of your computer!). What is the FreeBSD Ports Collection? -

People who (allegedly) know what they are doing have automated the -process of ``porting'' software to FreeBSD, and the result is the -Ports Collection. The general idea is that a combination of various -programming tools available in the base FreeBSD installation will -allow you to fetch the port from a FreeBSD mirror site, type ``make'' -and get the fully working program. +

When 2.0 was released, the FreeBSD Project decided to attempt to +automate the process of ``porting'' such software to FreeBSD, and the +result is the Ports Collection. The general idea was that a +combination of various programming tools already available in the base +FreeBSD installation would allow you to simply type `make' for a given +port and have the underlying ports mechanism automatically fetch the +port from a FreeBSD mirror site, apply any special configuration +knowledge to it and then build it to result in a fully working version +of the program. The ports collection itself normally doesn't have any of the original source code necessary for the compilation in the tree, just those shell scripts, Makefiles and source code ``diffs'' that are -necessary to compile the program under FreeBSD. This is meant to keep -the entire system down to a manageable size, and the current system -has over 100 ports in the master source tree, and yet a compressed tar -file of that tree is about 2 megabytes (all the source code needed is -over 100Mb's!). +necessary to configure and compile the program under FreeBSD. This +keeps the entire system down to a manageable size, with the current +system having over 300 ports in the master source tree and yet taking +up no more than a few tens of megabytes. How does the system compile with no source code? -

A ports' Makefile automatically looks in a central location on -your system (usually /usr/ports/distfiles, though this value can be +

The Makefile for a port automatically looks in a central location +on your system (usually /usr/ports/distfiles, though this value can be customized) for the associated set of original distribution files that -have been ``ported''. These are generally provided at various places -on the Internet, though if you have a CDROM distribution of FreeBSD -then you've already got them available on your CD for ease of use. -See section 3.1 if you have such a CD distribution, otherwise skip to -section 3.2. +have been ``ported''. Those not found locally are searched for +wherever they're generally provided on the Internet. If you have a +CDROM distribution of FreeBSD then you've already got them available +on your CD for ease of use. See if you have such a CDROM +distribution, otherwise skip to . - +

The ports collection is easy to use from CDROM, and all you need do +is create a "link tree" to it using the ``lndir'' command that comes +with the XFree86 distribution. Find a location with some +free space and create a directory there, then invoking the lndir +command with the full pathname of the ``ports'' directory on the CDROM +as an argument (this might be, for example, something like: ``lndir +/cdrom/ports''). Then you can build ports directly off the CDROM by +building them in the link tree you've created. -Compiling ports using an Internet connection +Compiling ports using an Internet connection

The ports collection can also use an auto-fetch system to keep your ports collection source tree up to date, updating the central ``distfiles'' version for you the next time you compile the port. - Of course, this always assumes you have a permanent network link, -or don't mind heavy usage of your telephone. If you don't want heavy -network usage when you compile your ports tree, you can pre-fetch the + Of course, this assumes you have a permanent network link or don't +mind heavy usage of your telephone. If you don't want heavy network +usage when you compile your ports tree, you can pre-fetch the necessary tarballs beforehand and put them into /usr/ports/distfiles (or wherever DISTDIR points) by hand. A good way to see what files a port is going to need is to cd to that port's directory and do a @@ -131,18 +140,6 @@ all-volunteer `ports committee' will (hopefully) look it over and commit it to the ports collection if they like the looks of it. -Things go funny during the fetch stage of compilation! - -

We know. Please don't blame us. There is a program called `ncftp' -which is used instead of the normal ftp as it can do so-called -``background'' or ``batch'' transfers, ideal for this situation. -Unfortunately it can do strange things, and has crashed at least one -machine (during circumstances stranger than most, I'll admit, but it -was still responsible). Hopefully a future release of ncftp will fix -these problems (it is not maintained by the main FreeBSD team, but a -third party, who is I believe aware of its shortcomings) - - I want to leave the compile going overnight, but some ports don't like this.

There is a way around this. Before starting the compilation, type: @@ -150,9 +147,7 @@ third party, who is I believe aware of its shortcomings) setenv BATCH yes # (if you use csh/tcsh) or BATCH=yes; export BATCH # (for sh/bash) - This should miss out ports which need user interaction. Unfortunately, -ncftp doesn't know about this trick, and can often screw up and ask -stupid questions in unattended batch mode. See (7). + This should skip ports which need user interaction to build. To compile those ports left out by doing the above, using a different login shell (or unsetting the above BATCH variable), set the @@ -195,15 +190,11 @@ time now! :-) How do I get more information on all the ports?

One good method is to cd to the top of the ports tree (say /usr/ports) -and type something like: +and type: - make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 + make print-index -The ``make describe'' will try to extract the one-line description from -each port, and the ``sed'' will delete the extraneous output. ``expand'' -just makes it a little more readable (sort of - you may want to season -the output of this more to taste). - +This will print a summary of all ports in the tree. I've heard of a new checksum system. What is this for? diff --git a/share/doc/handbook/submitters.sgml b/share/doc/handbook/submitters.sgml index 1bab4fccc5c5..cdeb85c342d5 100644 --- a/share/doc/handbook/submitters.sgml +++ b/share/doc/handbook/submitters.sgml @@ -1,4 +1,4 @@ - + Contributing to FreeBSD @@ -11,13 +11,13 @@ customizations or fixes to the system which they'd like to incorporate back into the mainstream sources, thus saving the work of having to re-integrate the changes for each subsequent FreeBSD release. Submitting something to the FreeBSD project is also an excellent way of getting your -code seriously tested! Many people have developed an original concept -far beyond what they might have envisioned at the start just due to the +code seriously tested! Many people have seen an original concept +develop far beyond what they might have envisioned at the start just due to the flood of feedback and ideas generated by the many thousands of users of FreeBSD. Contributions are also what FreeBSD lives and grows from, and so your contributions are very important to the continued survival of this communal effort of ours---we're very glad to see you reading this -documentation! +document! Submissions to FreeBSD can generally be classified into four catagories: @@ -203,7 +203,7 @@ 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: submitters.sgml,v 1.3 1995/06/20 16:29:55 jfieber Exp $ + $Id: submitters.sgml,v 1.4 1995/06/30 17:37:51 jfieber Exp $ For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. diff --git a/share/doc/handbook/sup.sgml b/share/doc/handbook/sup.sgml index f65db23c85ce..bafe6eeea432 100644 --- a/share/doc/handbook/sup.sgml +++ b/share/doc/handbook/sup.sgml @@ -1,4 +1,4 @@ - + @@ -88,4 +88,4 @@ ports-russian: /usr/ports/russian russian software ports-shells: /usr/ports/shells various UN*X shells ports-utils: /usr/ports/utils miscellaneous utilities ports-x11: /usr/ports/x11 X11 software - \ No newline at end of file + diff --git a/share/doc/handbook/troubleshooting.sgml b/share/doc/handbook/troubleshooting.sgml index 74db79a49000..07efb816fbfd 100644 --- a/share/doc/handbook/troubleshooting.sgml +++ b/share/doc/handbook/troubleshooting.sgml @@ -1,4 +1,4 @@ - + Troubleshooting @@ -41,15 +41,7 @@ address, IO address or a number of other device configuration parameters. You can also disable a device entirely if it's causing problems for other devices you'd - much rather have work. Note that this only affects the - kernel being booted temporarily, it does not write out - the information to the kernel so that these settings are - permanantly altered (this would be actually rather hard). - If you reboot, you'll have to make the same changes - again. The goal of the -c utility is to get you - up far enough to be able to download the appropriate - sources and configure and rebuild a kernel more specific - to your needs. + much rather have work. Another solution is, obviously, to remove the offending hardware or simply strip the system down to the bare @@ -61,17 +53,6 @@ - - My floppy-tape drive isn't probed - -

Cause: Last-minute problems with this driver caused it - to be disabled by default. - - Solution: Boot with -c (described above) and set the - flags value of fdc0 to 1. This will re-enable the floppy - tape driver. Sorry, but it was causing problems for - other people! - When I boot for the first time, it still looks for /386bsd! @@ -86,100 +67,3 @@ If you're installing for the first time, don't forget to (W)rite out your new boot blocks! :-) - - I want to boot FreeBSD off the second drive. It - doesn't! - -

Cause: FreeBSD will actually install just fine on a - drive other than 0 (the first drive), and the boot - manager will even allow you to select it, but the boot - blocks rather pathologically assume 0. This should be - fixed in 2.1. - - Solution: Easy - follow these steps: - - 1. Select the first (0) drive from the (F)disk editor - and write out the boot manager with the (B) option. - This will enable the boot manager that allows you to - actually boot off the other drive. - - 2. Exit the fdisk editor for the first drive and and - re-enter it again for the drive you wish to install - on. Set up a partition on this drive, or select - (A)ll for the entire drive. - - 3. Enter the disklabel editor and allocate space on - your second drive as normal. Proceed with the - installation. - - 4. Once you've installed on the disk and are going to - reboot from the hard disk, enter the following at - the boot prompt: - - hd(1,a)/kernel - - This will ensure that you really boot from the second - drive. If you've actually installed on a drive other - than 1 (the 3rd or 4th drive?), substitute that number - in for the above. You will need to enter this EVERY - time you reboot from the hard disk. If you're feeling - brave and have a srcdist + the requisite experience, - you can hack the boot blocks in: - - /usr/src/sys/i386/boot/biosboot - - So that this drive you're booting from is hard-coded. - Recompile the boot blocks and reinstall them on your - drive with `disklabel -B ...' You can then have the - default Do The Right Thing. - - - Newfs crashes, requesting that blocksize be 32K - -

Cause: You have your SCSI controller configured to - translate geometries for disks >1GB in size. - - Solution: Turn such translation OFF in your controller's - BIOS setup! FreeBSD has no problems with disks >1GB just - so long as the root partition starts and ends BELOW - cylinder 1024. This is a PC hardware limitation. - - - FreeBSD won't boot off the hard disk - -

Cause: Root partition does not start and end below - cylinder 1024. - - Solution: See solution for newfs crashes, or move your - root partition. This limitation holds true for ANY - operating system you wish to boot from your hard drive. - - - - FreeBSD still won't boot off the hard disk - -

Cause: No boot code is installed in sector 1. - - Solution: Chose the Write MBR (B)oot code in the FDISK - editor. - - - Nope, FreeBSD's still not booting from the hard - disk - -

Cause: BIOS disk geometry different from that used when - installing FreeBSD. - - Solution: With IDE drives, pay careful attention to the - geometry information that FreeBSD prints out when it's - first booting off the floppy. Use this geometry in your - BIOS setup or use the BIOS geometry when you install - FreeBSD. Either way, they have to match. - - With SCSI drives, the values they report is most often - bogus and cannot be used. In this situation, the SCSI - controller is performing geometry translation and it's - probably wise to assume a default of 64 heads, 32 sectors - and 1MB/cylinder. Use these values when you install - FreeBSD. See above comments concerning newfs failures - for more info.