pkgsrc/doc/guide/files/introduction.xml

<!-- $NetBSD: introduction.xml,v 1.14 2006/06/17 10:26:53 rillig Exp $ -->

<chapter id="introduction">
  <title>What is pkgsrc?</title>

  <sect1 id="introduction-section">
    <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><filename role="pkg">www/apache</filename> - The Apache
	  web server</para>
      </listitem>

      <listitem>
	<para><filename role="pkg">www/mozilla</filename> - The Mozilla
	  web browser</para>
      </listitem>

      <listitem>
	<para><filename role="pkg">meta-pkgs/gnome</filename> - The GNOME
	  Desktop Environment</para>
      </listitem>

      <listitem>
	<para><filename role="pkg">meta-pkgs/kde3</filename> - 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/">DragonFly BSD</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://h30097.www3.hp.com/">Tru64</ulink>
	  (Digital UNIX, OSF1)</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 three 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. The third part,
	<link linkend="infrastructure" endterm="infrastructure.title"/>
	is intended for those who want to understand how pkgsrc is
	implemented.</para>

	<para>This document is available in various formats:
	<simplelist type="inline">
	<member><ulink url="index.html">HTML</ulink></member>
	<member><ulink url="pkgsrc.pdf">PDF</ulink></member>
	<member><ulink url="pkgsrc.ps">PS</ulink></member>
	<member><ulink url="pkgsrc.txt">TXT</ulink></member>
	</simplelist>.</para>

  </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 bootstrapped 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>

<sect2 id="term.abbrev">
<title>Commonly used abbreviations</title>

	<variablelist>

	<varlistentry><term>ICE</term><listitem><para>Internal Compiler
	Error</para></listitem></varlistentry>

	</variablelist>

</sect2>

  <sect2 id="term.people">
  <title>People involved in pkgsrc</title>

	<variablelist>

	<varlistentry><term>pkgsrc users</term><listitem><para>The
	pkgsrc users are people who use the packages provided by pkgsrc.
	Typically they are system administrators. The people using the
	software that is inside the packages (maybe called <quote>end
	users</quote>) are not covered by the pkgsrc guide.</para>

	<para>There are two kinds of pkgsrc users: Some only want to
	install pre-built binary packages. Others build the pkgsrc
	packages from source, either for installing them directly or for
	building binary packages themselves. For pkgsrc users <xref
	linkend="users-guide"/> should provide all necessary
	documentation.</para></listitem></varlistentry>

	<varlistentry><term>package maintainers</term><listitem><para>A
	package maintainer creates packages as described in <xref
	linkend="developers-guide"/>.</para></listitem></varlistentry>

	<varlistentry><term>infrastructure developers</term>
	<listitem><para>These people are involved in all those files
	that live in the <filename>mk/</filename> directory and below.
	Only these people should need to read through <xref
	linkend="infrastructure"/>, though others might be curious,
	too.</para></listitem></varlistentry>

	</variablelist>

  </sect2>
  </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 &cprompt; for users'
      shell prompt, assuming they use the C-shell or tcsh.</para>
  </sect1>
</chapter>