pkgsrc/doc/guide/files/introduction.xml

<!-- $NetBSD: introduction.xml,v 1.15 2006/07/29 14:14:19 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 is usually available in form of the source code. Before
such software can be used, it needs to be configured to the local
system, compiled and installed, and this is exactly what The NetBSD
Packages Collection (pkgsrc) does. pkgsrc also has some basic commands
to handle binary packages, so that not every user has to build the
packages for himself, which is a time-costly task.</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>