pkgsrc/doc/guide/files/introduction.xml

<!-- $NetBSD: introduction.xml,v 1.2 2004/11/02 13:29:15 hubertf Exp $ -->

<chapter id="introduction">
  <title>Introduction</title>

  <sect1>
    <title>Introduction</title>

    <para> There is a lot of software freely available for Unix based
      systems, which usually runs on NetBSD and other Unix-flavoured
      systems, too, sometimes with some modifications.  The NetBSD
      Packages Collection (pkgsrc) incorporates any such changes
      necessary to make that software run, and makes the installation
      (and de-installation) of the software package easy by means of a
      single command. </para>

    <para>Once the software
      has been built, it is manipulated with the <command>pkg_*</command> tools
      so that installation
      and de-installation, printing of an inventory of all installed packages and
      retrieval of one-line comments or more verbose descriptions are all
      simple.</para>

    <para>pkgsrc currently contains several thousand packages,
      including:</para> 

    <itemizedlist>
      <listitem>
	<para><pkg>www/apache</pkg> - The Apache web server</para>
      </listitem>

      <listitem>
	<para><pkg>www/mozilla</pkg> - The Mozilla web browser</para>
      </listitem>

      <listitem>
	<para><pkg>meta-pkgs/gnome</pkg> - The GNOME Desktop Environment</para>
      </listitem>

      <listitem>
	<para><pkg>meta-pkgs/kde3</pkg> - The K Desktop Environment</para>
      </listitem>
    </itemizedlist>

    <para>...just to name a few.</para>

    <para>pkgsrc has built-in support for handling varying dependencies,
      such as pthreads and X11, and extended features such as IPv6 support on
      a range of platforms.</para>

    <para>pkgsrc was derived from FreeBSD's ports system, and
      initially developed for NetBSD only. Since then, pkgsrc has
      grown a lot, and now supports the following platforms:</para>

    <itemizedlist>
      <listitem>
	<para><ulink url="http://developer.apple.com/darwin/">Darwin</ulink>
	  (<ulink url="http://www.apple.com/macosx/">Mac OS X</ulink>)</para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.DragonFlyBSD.org/">DragonFlyBSD</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.FreeBSD.org/">FreeBSD</ulink></para>
      </listitem>

      <listitem>
	<para>Microsoft Windows, via <ulink url="http://www.microsoft.com/windows/sfu/">Interix</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.sgi.com/software/irix6.5/">IRIX</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.linux.org/">Linux</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.NetBSD.org/">NetBSD</ulink> (of
	  course)</para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.openbsd.org/">OpenBSD</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.sun.com/solaris/">Solaris</ulink></para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="overview">
    <title>Overview</title>

    <para>This document is divided into two parts.  The first,
      <link linkend="users-guide" endterm="users-guide.title"/>,
      describes how one can use one of the packages in the Package
      Collection, either by installing a precompiled binary package, or
      by building one's own copy using the &os; package system.  The
      second part,
      <link linkend="developers-guide" endterm="developers-guide.title"/>,
      explains how to prepare
      a package so it can be easily built by other &os; users without
      knowing about the package's building details.</para>

    <para>This document is available in various formats:</para>

    <itemizedlist>
      <listitem>
	<para><ulink url="index.html">HTML</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="pkgsrc.pdf">PDF</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="pkgsrc.ps">PS</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="pkgsrc.txt">TXT</ulink></para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="terminology">
    <title>Terminology</title>

    <para>There has been a lot of talk about <quote>ports</quote>,
      <quote>packages</quote>, etc. so far. Here is a description of all the
      terminology used within this document.</para>

    <variablelist>

      <varlistentry>
	<term>Package</term>

	<listitem>
	  <para>A set of files and building instructions
	    that describe what's necessary
	    to build a certain piece of software using
            pkgsrc. Packages are traditionally stored under 
	    <filename>/usr/pkgsrc</filename>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>The &os; package system</term>

	<listitem>
	  <para>
	    This is the former name of <quote>pkgsrc</quote>.  It is
	    part of the &os; operating system and can be bootstrap to
	    run on non-&os; operating systems as well.  It handles
	    building (compiling), installing, and removing of
	    packages.
	    </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Distfile</term>

	<listitem>
	  <para>This term describes the file or files that are
	    provided by the author of the piece of software to
	    distribute his work. All the changes necessary to build on
	    &os; are reflected in the corresponding package. Usually
	    the distfile is in the form of a compressed tar-archive,
	    but other types are possible, too. Distfiles are usually
	    stored below
	    <filename>/usr/pkgsrc/distfiles</filename>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Port</term>

	<listitem>
	  <para>This is the term used by FreeBSD and OpenBSD people
	    for what we call a package. 
	    In &os; terminology, <quote>port</quote> refers to a different
	    architecture.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Precompiled/binary package</term>

	<listitem>
	  <para>A set of binaries built with pkgsrc from a distfile
	    and stuffed together in a single <filename>.tgz</filename>
	    file so it can be installed on machines of the same
	    machine architecture without the need to
	    recompile. Packages are usually generated in
	    <filename>/usr/pkgsrc/packages</filename>; there is also
	    an archive on <ulink 
	    url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/">ftp.NetBSD.org</ulink>.</para> 

	  <para>Sometimes, this is referred to by the term <quote>package</quote> too,
	    especially in the context of precompiled packages.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Program</term>

	<listitem>
	  <para>The piece of software to be installed which will be constructed from
	    all the files in the Distfile by the actions defined in the
	    corresponding package.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 id="typography">
    <title>Typography</title>

    <para>When giving examples for commands, shell prompts are used to
      show if the command should/can be issued as root, or if
      <quote>normal</quote> user privileges are sufficient. We use a
      &rprompt; for root's shell prompt, and a &uprompt; for users'
      shell prompt, assuming they use the C-shell or tcsh.</para>
  </sect1>
</chapter>