<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="introduction">
  <chapterinfo>
    <authorgroup>
      <author>
        <firstname>Murray</firstname>
        <surname>Stokely</surname>
        <contrib>This chapter was written by </contrib>
      </author>
      <author>
        <firstname>Jeroen</firstname>
        <surname>Ruigrok van der Werven</surname>
      </author>
    </authorgroup>
  </chapterinfo>
  <title>Introduction</title>

  <sect1 id="introduction-devel">
    <title>Developing on FreeBSD</title>

    <para>So here we are.  System all installed and you are ready to
      start programming.  But where to start?  What does FreeBSD
      provide?  What can it do for me, as a programmer?</para>

    <para>These are some questions which this chapter tries to answer.
      Of course, programming has different levels of proficiency like
      any other trade.  For some it is a hobby, for others it is their
      profession.  The information in this chapter might be more aimed
      towards the beginning programmer, but may also serve to be
      useful for the programmer taking her first steps on the FreeBSD
      platform.</para>      

  </sect1>

  <sect1 id="introduction-bsdvision">
    <title>The BSD Vision</title>

    <para>To produce the best &unix; like operating system package
      possible, with due respect to the original software tools
      ideology as well as usability, performance and
      stability.</para>
  </sect1>
 
  <sect1 id="introduction-archguide">
    <title>Architectural Guidelines</title>

    <para>Our ideology can be described by the following
    guidelines</para>

    <itemizedlist>

      <listitem><para>Do not add new functionality unless an
        implementor cannot complete a real application without
        it.</para></listitem>

      <listitem><para>It is as important to decide what a system is
        not as to decide what it is. Do not serve all the world's
        needs; rather, make the system extensible so that additional
        needs can be met in an upwardly compatible
        fashion.</para></listitem>

      <listitem><para>The only thing worse than generalizing from one
        example is generalizing from no examples at
        all. </para></listitem>

      <listitem><para>If a problem is not completely understood, it is
        probably best to provide no solution at all.</para></listitem>

      <listitem><para>If you can get 90 percent of the desired effect
        for 10 percent of the work, use the simpler
        solution.</para></listitem>

      <listitem><para>Isolate complexity as much as
        possible.</para></listitem>

      <listitem><para>Provide mechanism, rather than policy. In
        particular, place user interface policy in the client's
        hands.</para></listitem>

     </itemizedlist>

     <para>From Scheifler & Gettys: "X Window System"</para>

  </sect1>

  <sect1 id="introduction-layout">
    <title>The Layout of 
      <filename class="directory">/usr/src</filename></title>

    <para>The complete source code to FreeBSD is available from our
      public CVS repository.  The source code is normally installed in
      <filename class=directory>/usr/src</filename> which contains the
      following subdirectories:</para>

    <para>
      <informaltable frame="none">
        <tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Directory</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>
	  
	  <tbody>
	    <row>
	    <entry><filename class=directory>bin/</filename></entry>
            <entry>Source for files in
            <filename>/bin</filename></entry>
	    </row>
	    
	    <row>
	    <entry><filename class=directory>contrib/</filename></entry>
	    <entry>Source for files from contributed software.</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>crypto/</filename></entry>
	    <entry>Cryptographical sources</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>etc/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/etc</filename></entry>
	    </row>

	    <row>
	    <entry><filename class=directory>games/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/usr/games</filename></entry>
	    </row>

	    <row>
	    <entry><filename class=directory>gnu/</filename></entry>
	    <entry>Utilities covered by the GNU Public License</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>include/</filename></entry>
            <entry>Source for files in <filename
            class=directory>/usr/include</filename></entry>
	    </row>

	    <row>
	    <entry><filename
 class=directory>kerberosIV/</filename></entry>
            <entry>Source for Kerberos version IV</entry>
	    </row>

	    <row>
	    <entry><filename
 class=directory>kerberos5/</filename></entry>
            <entry>Source for Kerberos version 5</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>lib/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/usr/lib</filename></entry>
	    </row>
	    
	    <row>
	    <entry><filename class=directory>libexec/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/usr/libexec</filename></entry>
	    </row>
	    
	    <row>
	    <entry><filename
 class=directory>release/</filename></entry>
            <entry>Files required to produce a FreeBSD release</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>sbin/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/sbin</filename></entry>
	    </row>

	    <row>
	    <entry><filename class=directory>secure/</filename></entry>
	    <entry>FreeSec sources</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>share/</filename></entry>
	    <entry>Source for files in <filename
	    class=directory>/usr/share</filename></entry>
	    </row>

	    <row>
	    <entry><filename class=directory>sys/</filename></entry>
	    <entry>Kernel source files</entry>
	    </row>

	    <row>
	    <entry><filename class=directory>tools/</filename></entry>
	    <entry>Tools used for maintenance and testing of
	    FreeBSD</entry>
	    </row>

	    <row>
	    <entry><filename
 class=directory>usr.bin/</filename></entry>
            <entry>Source for files in <filename
 class=directory>/usr/bin</filename></entry>
            </row>

	    <row>
	    <entry><filename
 class=directory>usr.sbin/</filename></entry>
            <entry>Source for files in <filename
 class=directory>/usr/sbin</filename></entry>
            </row>
          </tbody>
	</tgroup>
      </informaltable>
    </para>
  </sect1>
</chapter>
