article.xml revision 114787
176082Sbmah<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
276082Sbmah<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
376082Sbmah%man;
476082Sbmah<!ENTITY % authors PUBLIC  "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
576082Sbmah%authors;
676082Sbmah<!ENTITY % mlists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
776082Sbmah%mlists;
876082Sbmah<!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN">
976082Sbmah%release;
1082350Sbmah<!ENTITY % misc PUBLIC  "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
1182350Sbmah%misc;
1276082Sbmah]>
1376082Sbmah
1476082Sbmah<article>
1582666Sbmah  <articleinfo>
1682666Sbmah    <title>&os; &release.current; README</title>
1781327Sbmah
1882666Sbmah    <corpauthor>The &os; Project</corpauthor>
1981484Sbmah
2082666Sbmah    <pubdate>$FreeBSD: head/release/doc/en_US.ISO8859-1/readme/article.sgml 114787 2003-05-06 20:01:07Z bmah $</pubdate>
2181327Sbmah
2282666Sbmah    <copyright>
2382666Sbmah      <year>2000</year>
2482666Sbmah      <year>2001</year>
2588820Sbmah      <year>2002</year>
26108829Sbmah      <year>2003</year>
2782666Sbmah      <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation Project</holder>
2882666Sbmah    </copyright>
2982666Sbmah  </articleinfo>
3081327Sbmah
3182666Sbmah  <abstract>
3282666Sbmah    <para>This document gives a brief introduction to &os;
3388959Sbmah      &release.current;.  It includes some information on how to
3488959Sbmah      obtain &os;, a listing of various ways to contact the &os;
3588959Sbmah      Project, and pointers to some other sources of
3688959Sbmah      information.</para>
3782666Sbmah  </abstract>
3881327Sbmah
39109143Sroam  <sect1 id="intro">
4082666Sbmah    <title>Introduction</title>
4181327Sbmah
4282666Sbmah    <para>This distribution is a &release.type; of &os; &release.current;, the
4382666Sbmah      latest point along the &release.branch; branch.</para>
4481327Sbmah
4582666Sbmah    <sect2>
4682666Sbmah      <title>About &os;</title>
4781327Sbmah
4882666Sbmah      <para>&os; is an operating system based on 4.4 BSD Lite for
4982666Sbmah	Intel, AMD, Cyrix or NexGen <quote>x86</quote> based PC
50114787Sbmah	hardware (i386), NEC PC-9801/9821 series PCs and compatibles
51114787Sbmah	(pc98), DEC/Compaq/HP Alpha computers (alpha), 
52114787Sbmah	and UltraSPARC machines (sparc64).  Versions
53114787Sbmah	for the IA64 (ia64), PowerPC (powerpc), and AMD
54114787Sbmah	<quote>Hammer</quote> (amd64) architectures are currently under
5582666Sbmah	development as well.  &os; works with a wide variety of
5682666Sbmah	peripherals and configurations and can be used for everything
5782666Sbmah	from software development to games to Internet Service
5882666Sbmah	Provision.</para>
5981327Sbmah
6082666Sbmah      <para>This release of &os; contains everything you need to run
6182666Sbmah	such a system, including full source code for the kernel and
6282666Sbmah	all utilities in the base distribution.  With the source
6382666Sbmah	distribution installed, you can literally recompile the entire
6482666Sbmah	system from scratch with one command, making it ideal for
6582666Sbmah	students, researchers, or users who simply want to see how it
6682666Sbmah	all works.</para>
6781327Sbmah
6882666Sbmah      <para>A large collection of third-party ported software (the
6982666Sbmah	<quote>Ports Collection</quote>) is also provided to make it
70114787Sbmah	easy to obtain and install all your favorite traditional &unix;
7182666Sbmah	utilities for &os;.  Each <quote>port</quote> consists of a
7282666Sbmah	set of scripts to retrieve, configure, build, and install a
7382666Sbmah	piece of software, with a single command.  Over &os.numports;
7482666Sbmah	ports, from editors to programming languages to graphical
7582666Sbmah	applications, make &os; a powerful and comprehensive operating
7682666Sbmah	environment that extends far beyond what's provided by many
77114787Sbmah	commercial versions of &unix;.  Most ports are also available as
7882666Sbmah	pre-compiled <quote>packages</quote>, which can be quickly
7982666Sbmah	installed from the installation program.</para>
8082666Sbmah    </sect2>
8182666Sbmah
8282666Sbmah    <sect2>
8382666Sbmah      <title>Target Audience</title>
8482666Sbmah
8581339Sbmah<![ %release.type.snapshot; [
8681327Sbmah
8782666Sbmah      <para>This &release.type; is aimed primarily at early adopters
8882666Sbmah	and various other users who want to get involved with the
8982666Sbmah	ongoing development of &os;.  While the &os; development team
9082666Sbmah	tries its best to ensure that each &release.type; works as
9182666Sbmah	advertised, &release.branch; is very much a
9282666Sbmah	work-in-progress.</para>
9381327Sbmah
9493244Skeramida      <para>The basic requirements for using this &release.type; are
9582666Sbmah	technical proficiency with &os; and an understanding of the
9683425Sbmah	ongoing development process of &os; &release.branch; (as
9782666Sbmah	discussed on the &a.current;).</para>
9882666Sbmah
9982666Sbmah      <para>For those more interested in doing business with &os; than
10082666Sbmah	in experimenting with new &os; technology, formal releases
10192482Smurray	(such as &release.prev.stable;) are frequently more appropriate.
10282666Sbmah	Releases undergo a period of testing and quality assurance
10382666Sbmah	checking to ensure high reliability and dependability.</para>
10482666Sbmah
10581339Sbmah]]>
10681339Sbmah
10781339Sbmah<![ %release.type.release; [
10882666Sbmah
10982666Sbmah      <para>This &release.type; of &os; is suitable for all users.  It
11082666Sbmah	has undergone a period of testing and quality assurance
11182666Sbmah	checking to ensure the highest reliability and
11282666Sbmah	dependability.</para>
11382666Sbmah
11481339Sbmah]]>
11581339Sbmah
11682666Sbmah    </sect2>
11782666Sbmah  </sect1>
11881339Sbmah
119109143Sroam  <sect1 id="obtain">
12082666Sbmah    <title>Obtaining &os;</title>
12181327Sbmah
12282666Sbmah    <para>&os; may be obtained in a variety of ways.  This section
12388959Sbmah      focuses on those ways that are primarily useful for obtaining a
12482666Sbmah      complete &os; distribution, rather than updating an existing
12582666Sbmah      installation.</para>
12681327Sbmah
12782666Sbmah    <sect2>
12882666Sbmah      <title>CDROM and DVD</title>
12981327Sbmah
13082666Sbmah      <para>&os; -RELEASE distributions may be ordered on CDROM or DVD
13182666Sbmah	from several publishers.  This is frequently the most
13282666Sbmah	convenient way to obtain &os; for new installations, as it
13382666Sbmah	provides a convenient way to quickly reinstall the system if
13482666Sbmah	necessary.  Some distributions include some of the optional,
13582666Sbmah	precompiled <quote>packages</quote> from the &os; Ports
13682666Sbmah	Collection.</para>
13781327Sbmah
13882666Sbmah      <para>A list of the CDROM and DVD publishers known to the
13982666Sbmah	project are listed in the <ulink
14082666Sbmah	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mirrors.html"><quote>Obtaining
14182666Sbmah	FreeBSD</quote></ulink> appendix to the Handbook.</para>
14282666Sbmah    </sect2>
14381327Sbmah
14482666Sbmah    <sect2>
14582666Sbmah      <title>FTP</title>
14681327Sbmah
14782666Sbmah      <para>You can use FTP to retrieve &os; and any or all of its
14882666Sbmah	optional packages from <ulink
14982666Sbmah	url="ftp://ftp.FreeBSD.org/"></ulink>, which is the official
15082666Sbmah	&os; release site, or any of its
15182666Sbmah	<quote>mirrors</quote>.</para>
15281327Sbmah
15382666Sbmah      <para>Lists of locations that mirror &os; can be found in the
15482666Sbmah	<ulink
15582666Sbmah	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mirrors-ftp.html">FTP
15682666Sbmah	Sites</ulink> section of the Handbook, or on the <ulink
15782666Sbmah	url="http://www.freebsdmirrors.org/"></ulink> Web pages.
15882666Sbmah	Finding a close (in networking terms) mirror from which to
15982666Sbmah	download the distribution is highly recommended.</para>
16081327Sbmah
16182666Sbmah      <para>Additional mirror sites are always welcome.  Contact
16282666Sbmah	<email>freebsd-admin@FreeBSD.org</email> for more details on
16391249Skeramida	becoming an official mirror site.  You can also find useful
16491249Skeramida        information for mirror sites at the <ulink
16591249Skeramida        URL="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/hubs/">Mirroring
16691249Skeramida        FreeBSD</ulink> article.</para>
16781327Sbmah
16882666Sbmah      <para>Mirrors generally contain the floppy disk images necessary
16982666Sbmah	to begin an installation, as well as the distribution files
17088959Sbmah	needed for the install process itself.  Many mirrors also
17188959Sbmah	contain the ISO images necessary to create a CDROM of
17282666Sbmah	a &os; release.</para>
17381327Sbmah
17482666Sbmah    </sect2>
17582666Sbmah  </sect1>
17681327Sbmah
17782666Sbmah  <sect1 id="contacting">
17882666Sbmah    <title>Contacting the &os; Project</title>
17981327Sbmah
18082666Sbmah    <sect2>
18182666Sbmah      <title>Email and Mailing Lists</title>
18281327Sbmah
18382666Sbmah      <para>For any questions or general technical support issues,
18482666Sbmah	please send mail to the &a.questions;.</para>
18581327Sbmah
18683425Sbmah      <para>If you're tracking the &release.branch; development efforts, you
18782666Sbmah	<emphasis>must</emphasis> join the &a.current;, in order to
18882666Sbmah	keep abreast of recent developments and changes that may
18993244Skeramida	affect the way you use and maintain the system.</para>
19081327Sbmah
19188959Sbmah      <para>Being a largely-volunteer effort, the &os;
19288959Sbmah	Project is always happy to have extra hands willing to help&mdash;there are already far more desired enhancements than
19382666Sbmah	there is time to implement them.  To contact the developers on
19482666Sbmah	technical matters, or with offers of help, please send mail to
19582666Sbmah	the &a.hackers;.</para>
19681327Sbmah
19782666Sbmah      <para>Please note that these mailing lists can experience
19888959Sbmah	<emphasis>significant</emphasis> amounts of traffic.  If you
19988959Sbmah	have slow or expensive mail access, or are only interested in
20088959Sbmah	keeping up with major &os; events, you may find it
20182666Sbmah	preferable to subscribe instead to the &a.announce;.</para>
20281327Sbmah
20382666Sbmah      <para>All of the mailing lists can be freely joined by anyone
204114787Sbmah	wishing to do so.  Visit the <ulink url="http://www.FreeBSD.org/mailman/listinfo">
205114236Shrs	FreeBSD Mailman Info Page</ulink>.  This will give you more
20682666Sbmah	information on joining the various lists, accessing archives,
20782666Sbmah	etc.  There are a number of mailing lists targeted at special
20882666Sbmah	interest groups not mentioned here; more information can be
209114787Sbmah	obtained either from the Mailman pages or the <ulink
21082666Sbmah	url="http://www.FreeBSD.org/support.html#mailing-list">mailing
21182666Sbmah	lists section</ulink> of the &os; Web site.</para>
21281327Sbmah
21382666Sbmah      <important>
21482666Sbmah	<para>Do <emphasis>not</emphasis> send email to the lists
215114787Sbmah	  asking to be subscribed.  Use the Mailman interface
21682666Sbmah	  instead.</para>
21782666Sbmah      </important>
21882666Sbmah    </sect2>
21981327Sbmah
22082666Sbmah    <sect2>
22182666Sbmah      <title>Submitting Problem Reports</title>
22281327Sbmah
22382666Sbmah      <para>Suggestions, bug reports and contributions of code are
22488959Sbmah	always valued&mdash;please do not hesitate to report any
22582666Sbmah	problems you may find.  Bug reports with attached fixes are of
22682666Sbmah	course even more welcome.</para>
22781327Sbmah
22882666Sbmah      <para>The preferred method to submit bug reports from a machine
22982666Sbmah	with Internet mail connectivity is to use the &man.send-pr.1;
230114787Sbmah	command.
23182666Sbmah	<quote>Problem Reports</quote> (PRs) submitted in this way
23282666Sbmah	will be filed and their progress tracked; the &os; developers
23382666Sbmah	will do their best to respond to all reported bugs as soon as
23482666Sbmah	possible.  <ulink
23582666Sbmah	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">A list
23682666Sbmah	of all active PRs</ulink> is available on the &os; Web site;
23782666Sbmah	this list is useful to see what potential problems other users
23882666Sbmah	have encountered.</para>
23981327Sbmah
24082666Sbmah      <para>Note that &man.send-pr.1; itself is a shell script that
24182666Sbmah	should be easy to move even onto a non-&os; system.  Using
24282666Sbmah	this interface is highly preferred.  If, for some reason, you
24382666Sbmah	are unable to use &man.send-pr.1; to submit a bug report, you
24482666Sbmah	can try to send it to the &a.bugs;.</para>
24581327Sbmah
24688959Sbmah      <para>For more information, <ulink
24788959Sbmah	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/problem-reports/"><quote>Writing
24888959Sbmah	FreeBSD Problem Reports</quote></ulink>, available on the &os; Web
24988959Sbmah	site, has a number of helpful hints on writing and submitting
25088959Sbmah	effective problem reports.</para>
25182666Sbmah    </sect2>
25282666Sbmah  </sect1>
25381339Sbmah
254109143Sroam  <sect1 id="seealso">
25582666Sbmah    <title>Further Reading</title>
25681339Sbmah
25788959Sbmah    <para>There are many sources of information about &os;; some are
25888959Sbmah      included with this distribution, while others are available
25988959Sbmah      on-line or in print versions.</para>
26088959Sbmah
26182666Sbmah    <sect2 id="release-docs">
26282666Sbmah      <title>Release Documentation</title>
26381339Sbmah
26482666Sbmah      <para>A number of other files provide more specific information
26582666Sbmah	about this &release.type; distribution.  These files are
26682666Sbmah	provided in various formats.  Most distributions will include
26782666Sbmah	both ASCII text (<filename>.TXT</filename>) and HTML
26882666Sbmah	(<filename>.HTM</filename>) renditions.  Some distributions
26982666Sbmah	may also include other formats such as PostScript
27082666Sbmah	(<filename>.PS</filename>) or Portable Document Format
27182666Sbmah	(<filename>.PDF</filename>).
27281339Sbmah
27382666Sbmah	<itemizedlist>
27482666Sbmah	  <listitem>
27582666Sbmah	    <para><filename>README.TXT</filename>: This file, which
27682666Sbmah	      gives some general information about &os; as well as
27782666Sbmah	      some cursory notes about obtaining a
27882666Sbmah	      distribution.</para>
27982666Sbmah	  </listitem>
28081339Sbmah
28182666Sbmah	  <listitem>
282105992Sbmah	    <para><filename>EARLY.TXT</filename>: A guide for early
283114787Sbmah	      adopters of &os; &release.current;.  Highly recommended
284105992Sbmah	      reading for users new to &os; &release.branch; and/or the
285105992Sbmah	      5.<replaceable>X</replaceable> series of releases.</para>
286105992Sbmah	  </listitem>
287105992Sbmah
288105992Sbmah	  <listitem>
28982666Sbmah	    <para><filename>RELNOTES.TXT</filename>: The release
29082666Sbmah	      notes, showing what's new and different in &os;
29188959Sbmah	      &release.current; compared to the previous release (&os;
29288959Sbmah	      &release.prev;).</para>
29382666Sbmah	  </listitem>
29481339Sbmah
29582666Sbmah	  <listitem>
29682666Sbmah	    <para><filename>HARDWARE.TXT</filename>: The hardware
29786152Solgeni	      compatibility list, showing devices with which &os; has
29882666Sbmah	      been tested and is known to work.</para>
29982666Sbmah	  </listitem>
30081339Sbmah
30182666Sbmah	  <listitem>
30282666Sbmah	    <para><filename>INSTALL.TXT</filename>: Installation
30382666Sbmah	      instructions for installing &os; from its distribution
30482666Sbmah	      media.</para>
30582666Sbmah	  </listitem>
30681339Sbmah
30782666Sbmah	  <listitem>
30882666Sbmah	    <para><filename>ERRATA.TXT</filename>: Release errata.
30982666Sbmah	      Late-breaking, post-release information can be found in
31082666Sbmah	      this file, which is principally applicable to releases
31182666Sbmah	      (as opposed to snapshots).  It is important to consult
31282666Sbmah	      this file before installing a release of &os;, as it
31382666Sbmah	      contains the latest information on problems which have
31482666Sbmah	      been found and fixed since the release was
31582666Sbmah	      created.</para>
31682666Sbmah	  </listitem>
31782666Sbmah	</itemizedlist>
31888959Sbmah
31988959Sbmah	<note>
32088959Sbmah	  <para>Several of these documents (in particular,
32188959Sbmah	    <filename>RELNOTES.TXT</filename>,
32288959Sbmah	    <filename>HARDWARE.TXT</filename>, and
32388959Sbmah	    <filename>INSTALL.TXT</filename>) contain information that
32488959Sbmah	    is specific to a particular hardware architecture.  For
32588959Sbmah	    example, the alpha release notes contain information not
32688959Sbmah	    applicable to the i386, and vice versa.  The architecture
32788959Sbmah	    for which each document applies will be listed in that
32888959Sbmah	    document's title.</para>
32988959Sbmah	</note>
33088959Sbmah
33182666Sbmah      </para>
33281339Sbmah
33393443Sbmah      <para>On platforms that support &man.sysinstall.8; (currently
334114787Sbmah	alpha, i386, ia64, pc98, and sparc64), these documents are generally available via the
33583425Sbmah	Documentation menu during installation.  Once the system is
33693443Sbmah	installed, you can revisit this menu by re-running the
33783425Sbmah	&man.sysinstall.8; utility.</para>
33881339Sbmah
33982666Sbmah      <note>
34082666Sbmah	<para>It is extremely important to read the errata for any
34182666Sbmah	  given release before installing it, to learn about any
34282666Sbmah	  <quote>late-breaking news</quote> or post-release problems.
34382666Sbmah	  The errata file accompanying each release (most likely right
34482666Sbmah	  next to this file) is already out of date by definition, but
34582666Sbmah	  other copies are kept updated on the Internet and should be
34682666Sbmah	  consulted as the <quote>current errata</quote> for this
34782666Sbmah	  release.  These other copies of the errata are located at
34882666Sbmah	  <ulink url="http://www.FreeBSD.org/releases/"></ulink> (as
34982666Sbmah	  well as any sites which keep up-to-date mirrors of this
35082666Sbmah	  location).</para>
35182666Sbmah      </note>
35282666Sbmah    </sect2>
35383425Sbmah
35483425Sbmah    <sect2>
35588959Sbmah      <title>Manual Pages</title>
35688959Sbmah
357114787Sbmah      <para>As with almost all &unix;-like operating systems, &os; comes
35888959Sbmah	with a set of on-line manual pages, accessed through the
35988959Sbmah	&man.man.1; command or through the <ulink
36088959Sbmah	url="http://www.FreeBSD.org/cgi/man.cgi">hypertext manual
36188959Sbmah	pages gateway</ulink> on the &os; Web site.  In general, the
36288959Sbmah	manual pages provide information on the different commands and
36388959Sbmah	APIs available to the &os; user.</para>
36488959Sbmah
365107569Sbmah      <para>In some cases, manual pages are written to give
36688959Sbmah	information on particular topics.  Notable examples of such
36788959Sbmah	manual pages are &man.tuning.7; (a guide to performance tuning),
36888959Sbmah	&man.security.7; (an introduction to &os; security), and
36988959Sbmah	&man.style.9; (a style guide to kernel coding).</para>
37088959Sbmah    </sect2>
37188959Sbmah
37288959Sbmah    <sect2>
37383425Sbmah      <title>Books and Articles</title>
37483425Sbmah
37583425Sbmah      <para>Two highly-useful collections of &os;-related information,
37683425Sbmah	maintained by the &os; Project,
37783425Sbmah	are the &os; Handbook and &os; FAQ (Frequently Asked
37883425Sbmah	Questions document).  On-line versions of the <ulink
37983425Sbmah	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/">Handbook</ulink>
38083425Sbmah	and <ulink
38183425Sbmah	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/">FAQ</ulink>
38283425Sbmah	are always available from the <ulink
38383425Sbmah	url="http://www.FreeBSD.org/docs.html">FreeBSD Documentation
38483425Sbmah	page</ulink> or its mirrors.  If you install the
38583425Sbmah	<filename>doc</filename> distribution set, you can use a Web
38683425Sbmah	browser to read the Handbook and FAQ locally.</para>
38783425Sbmah
38884484Sbmah      <para>A number of on-line books and articles, also maintained by
38984484Sbmah        the &os; Project, cover more-specialized, &os;-related topics.
39084484Sbmah        This material spans a wide range of topics, from effective use
39184484Sbmah        of the mailing lists, to dual-booting &os; with other
39284484Sbmah        operating systems, to guidelines for new committers.  Like the
39384484Sbmah        Handbook and FAQ, these documents are available from the &os;
39484484Sbmah        Documentation Page or in the <filename>doc</filename>
39584484Sbmah        distribution set.</para>
39684484Sbmah
39784484Sbmah      <para>A listing of other books and documents about &os; can be
39883425Sbmah        found in the <ulink
39983425Sbmah        url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/bibliography.html">bibliography</ulink>
400114787Sbmah        of the &os; Handbook.  Because of &os;'s strong &unix; heritage,
401114787Sbmah        many other articles and books written for &unix; systems are
40283425Sbmah        applicable as well, some of which are also listed in the
40383425Sbmah        bibliography.</para>
40483425Sbmah    </sect2>
40582666Sbmah  </sect1>
40681327Sbmah
407109143Sroam  <sect1 id="acknowledgements">
40882666Sbmah    <title>Acknowledgments</title>
40981327Sbmah
41082666Sbmah    <para>&os; represents the cumulative work of many hundreds, if not
41182666Sbmah      thousands, of individuals from around the world who have worked
41282666Sbmah      countless hours to bring about this &release.type;.  For a
41382666Sbmah      complete list of &os; developers and contributors, please see
41482666Sbmah      <ulink
41588959Sbmah      url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/"><quote>Contributors
41688959Sbmah      to FreeBSD</quote></ulink> on the &os; Web site or any of its
41782666Sbmah      mirrors.</para>
41881327Sbmah
41982666Sbmah    <para>Special thanks also go to the many thousands of &os; users
42082666Sbmah      and testers all over the world, without whom this &release.type;
42182666Sbmah      simply would not have been possible.</para>
42282666Sbmah  </sect1>
42376082Sbmah</article>
42482666Sbmah
42582666Sbmah<!-- 
42682666Sbmah     Local Variables:
42782666Sbmah     mode: sgml
42882666Sbmah     sgml-indent-data: t
42982666Sbmah     sgml-omittag: nil
43082666Sbmah     sgml-always-quote-attributes: t
43182666Sbmah     End:
43282666Sbmah-->
433