diff options
| author | grant <grant@pkgsrc.org> | 2004-10-21 14:27:36 +0000 |
|---|---|---|
| committer | grant <grant@pkgsrc.org> | 2004-10-21 14:27:36 +0000 |
| commit | 798a931bb4ab35d36ad4fe7903f4ab0d5c13d552 (patch) | |
| tree | 33c12f96b885de4e38aaf259542d73ad55e5f341 | |
| parent | 113c554381770570a4e3e6d8417218394e384a08 (diff) | |
| download | pkgsrc-798a931bb4ab35d36ad4fe7903f4ab0d5c13d552.tar.gz | |
import The pkgsrc guide, the docbook conversion/replacement of
Packages.txt; Packages.txt will be going away.
this package contains the source files and a mechanism to install
pkgsrc/doc/pkgsrc.{html,txt} which are distributed with pkgsrc. it
uses the same docbook infrastructure that is used to build the
documentation on www.NetBSD.org.
29 files changed, 7820 insertions, 0 deletions
diff --git a/doc/guide/DESCR b/doc/guide/DESCR new file mode 100644 index 00000000000..2386526a45a --- /dev/null +++ b/doc/guide/DESCR @@ -0,0 +1,4 @@ +The pkgsrc guide is a package containing the pkgsrc user and developer +documentation. It is written in DocBook/XML and supports a number of +outputs including PostScript, PDF, browsable (split) HTML, a single +HTML file and plain text. diff --git a/doc/guide/Makefile b/doc/guide/Makefile new file mode 100644 index 00000000000..17b965eb321 --- /dev/null +++ b/doc/guide/Makefile @@ -0,0 +1,97 @@ +# $NetBSD: Makefile,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ +# + +DISTNAME= htdocs-share-20041021 +PKGNAME= pkgsrc-guide-${PKGVERSION} +CATEGORIES= # empty +MASTER_SITES= ${MASTER_SITE_LOCAL} + +MAINTAINER= packages@NetBSD.org +HOMEPAGE= http://www.NetBSD.org/Documentation/pkgsrc/ +COMMENT= The pkgsrc guide + +# the "install-doc" target installs pkgsrc/doc/pkgsrc.{html,txt} which +# both need to be committed to CVS. + +PKGVERSION!= date '+%Y%m%d' +DIST_SUBDIR= ${PKGBASE} +NO_CONFIGURE= # defined +NO_MTREE= # defined +USE_LANGUAGES= # empty + +PLIST_SRC= ${WRKDIR}/PLIST_DYNAMIC +DOCDIR= ${PREFIX}/share/doc/pkgsrc + +BUILD_DEFS+= OUTPUTS +OUTPUTS?= html html-split ascii + +# the html is needed to build the ascii version. +.if !empty(OUTPUTS:Mascii) +OUTPUTS+= html +.endif + +# html output +BUILD_DEPENDS+= docbook>=4.0:../../textproc/docbook +BUILD_DEPENDS+= docbook-xml>=4.0:../../textproc/docbook-xml +BUILD_DEPENDS+= docbook-xsl>=1.62.4:../../textproc/docbook-xsl +BUILD_DEPENDS+= dsssl-docbook-modular>=1.54:../../textproc/dsssl-docbook-modular +BUILD_DEPENDS+= opensp>=1.5:../../textproc/opensp +BUILD_DEPENDS+= libxslt>=1.0.30:../../textproc/libxslt + +.if !empty(OUTPUTS:Mhtml*) +BUILD_DEPENDS+= tidy>=20021108:../../www/tidy +.endif + +.if !empty(OUTPUTS:Mascii) +BUILD_DEPENDS+= w3m>=0.4:../../www/w3m +.endif + +.if !empty(OUTPUTS:Mps) || !empty(OUTPUTS:Mpdf) +BUILD_DEPENDS+= openjade>=1.3.2:../../textproc/openjade +BUILD_DEPENDS+= tex-jadetex>=3.13:../../print/tex-jadetex +USE_GHOSTSCRIPT= build +GHOSTSCRIPT_REQD= 7.05 +. include "../../mk/ghostscript.mk" +.endif + +pre-extract: + @cd ${FILESDIR} && ${PAX} -rw . ${WRKSRC} + +do-build: +.for _output_ in ${OUTPUTS} + @cd ${WRKSRC} && ${SETENV} ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} ${_output_} +.endfor + +do-install: + ${INSTALL_DATA_DIR} ${DOCDIR} +.if !empty(OUTPUTS:Mhtml) || !empty(OUTPUTS:Mhtml-split) + ${INSTALL_DATA} ${WRKSRC}/*.html ${DOCDIR} + ${INSTALL_DATA} ${WRKDIR}/htdocs/NetBSD.css ${DOCDIR} +.endif +.if !empty(OUTPUTS:Mascii) + ${INSTALL_DATA} ${WRKSRC}/pkgsrc.txt ${DOCDIR} +.endif +.if !empty(OUTPUTS:Mpdf) + ${INSTALL_DATA} ${WRKSRC}/pkgsrc.ps ${DOCDIR} + ${INSTALL_DATA} ${WRKSRC}/pkgsrc.pdf ${DOCDIR} +.endif + +post-install: + @${FIND} ${DOCDIR} \( -type f -o -type l \) -print \ + | ${SORT} | ${SED} -e "s,${PREFIX}/,,g" \ + >> ${PLIST_SRC} + @${FIND} ${DOCDIR} -type d -print \ + | ${SORT} -r | ${SED} -e "s,${PREFIX}/,@dirrm ,g" \ + >> ${PLIST_SRC} + +# install the single-file HTML and ascii output into the pkgsrc doc/ +# directory, for distribution with pkgsrc. +# +# note that this uses ${CP} and not ${INSTALL_DATA} because this +# shouldn't be done as root. +# +install-doc: build + ${CP} ${WRKSRC}/pkgsrc.html ${_PKGSRCDIR}/doc + ${CP} ${WRKSRC}/pkgsrc.txt ${_PKGSRCDIR}/doc + +.include "../../mk/bsd.pkg.mk" diff --git a/doc/guide/PLIST b/doc/guide/PLIST new file mode 100644 index 00000000000..94b6c773db3 --- /dev/null +++ b/doc/guide/PLIST @@ -0,0 +1,2 @@ +@comment $NetBSD: PLIST,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ +@comment this PLIST automatically generated diff --git a/doc/guide/distinfo b/doc/guide/distinfo new file mode 100644 index 00000000000..77f6845210a --- /dev/null +++ b/doc/guide/distinfo @@ -0,0 +1,4 @@ +$NetBSD: distinfo,v 1.1.1.1 2004/10/21 14:27:36 grant Exp $ + +SHA1 (pkgsrc-guide/htdocs-share-20041021.tar.gz) = f1aae7efc7a31d703dfb14633fa5ac6620923137 +Size (pkgsrc-guide/htdocs-share-20041021.tar.gz) = 27822 bytes diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile new file mode 100644 index 00000000000..3a4e9c58ca0 --- /dev/null +++ b/doc/guide/files/Makefile @@ -0,0 +1,42 @@ +# $NetBSD: Makefile,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ + +WEB_PREFIX= ${.CURDIR}/../htdocs + +DOC= pkgsrc + +SRCS= pkgsrc.xml +SRCS+= binary.xml +SRCS+= build.xml +SRCS+= buildlink.xml +SRCS+= components.xml +SRCS+= debug.xml +SRCS+= examples.xml +SRCS+= faq.xml +SRCS+= fixes.xml +SRCS+= ftp-layout.xml +SRCS+= getting.xml +SRCS+= introduction.xml +SRCS+= logs.xml +SRCS+= options.xml +SRCS+= platforms.xml +SRCS+= plist.xml +SRCS+= submit.xml +SRCS+= using.xml + +# entities +SRCS+= chapters.ent + +# Make deeper TOC: +XSL_DBX_WITH_TOC_SECTION_DEPTH?= 2 + + +all: # doing this as depends doesn't work + -${MAKE} html-split + -${MAKE} html + -${MAKE} ascii + -${MAKE} pdf + +netbsd.pdf: pdf +netbsd.txt: ascii + +.include "${WEB_PREFIX}/share/mk/doc.docbook.mk" diff --git a/doc/guide/files/binary.xml b/doc/guide/files/binary.xml new file mode 100644 index 00000000000..7367d946737 --- /dev/null +++ b/doc/guide/files/binary.xml @@ -0,0 +1,421 @@ +<!-- $NetBSD: binary.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="binary"> + <title>Creating binary packages</title> + + <sect1> + <title>Building a single binary package</title> + + <para>Once you have built and installed a package, you can create a + <emphasis>binary package</emphasis> which can be installed on another + system with &man.pkg.add.1; This saves having to build the same package on + a group of hosts and wasting CPU time. It also provides a simple means + for others to install your package, should you distribute it.</para> + + <para>To create a binary package, change into the appropriate + directory in pkgsrc, and run <command>make package</command>:</para> + + <screen>&rprompt; <userinput>cd misc/figlet</userinput> +&rprompt; <userinput>make package</userinput></screen> + + <para>This will build and install your package (if not already done), and then + build a binary package from what was installed. You can then use the + <command>pkg_*</command> tools to manipulate it. Binary packages are + created by default in <filename>/usr/pkgsrc/packages</filename>, in the + form of a gzipped tar file. See <xref linkend="logs.package"/> for + a continuation of the above <pkg>misc/figlet</pkg> example.</para> + + <para>See <xref linkend="submit"/> for information on how to submit such a + binary package.</para> + </sect1> + + <sect1> + <title>Settings for creation of binary packages</title> + + <para>See <xref linkend="build.helpful-targets"/>.</para> + </sect1> + + <sect1 id="bulkbuild"> + <title>Doing a bulk build of all packages</title> + + <para>If you want to get a full set of precompiled binary packages, this section + describes how to get them. Beware that the bulk build will remove all + currently installed packages from your system! Having a FTP server + configured either on the machine doing the bulk builds or on a nearby NFS + server can help to make the packages available to everyone. See + &man.ftpd.8; for + more information. If you use a remote NFS server's storage, be sure to not + actually compile on NFS storage, as this slows things down a lot.</para> + + <sect2 id="binary.configuration"> + <title>Configuration</title> + + <sect3 id="binary.mk.conf"> + <title>/etc/mk.conf</title> + + <para>You may want to set things in <filename>/etc/mk.conf</filename>. + Look at <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename> for + details of the default settings. You will want to ensure that + <varname>ACCEPTABLE_LICENSES</varname> meet your local policy. + As used in this example, <varname>_ACCEPTABLE=yes</varname> + accepts <emphasis>all</emphasis> licenses.</para> + + <programlisting>PACKAGES?= ${_PKGSRCDIR}/packages/${MACHINE_ARCH} +WRKOBJDIR?= /usr/tmp/pkgsrc # build here instead of in pkgsrc +BSDSRCDIR= /usr/src +BSDXSRCDIR= /usr/xsrc # for x11/xservers +OBJHOSTNAME?= yes # use work.`hostname` +FAILOVER_FETCH= yes # insist on the correct checksum +PKG_DEVELOPER?= yes +_ACCEPTABLE= yes</programlisting> + </sect3> + + <sect3> + <title><filename>build.conf</filename></title> + + <para>In <filename>pkgsrc/mk/bulk</filename>, copy + <filename>build.conf-example</filename> to + <filename>build.conf</filename> and + edit it, following the comments in that file. This is the config + file that determines where log files are generated after the build, + where to mail the build report to, where your pkgsrc tree is located and + which user to &man.su.8; to to do a <command>cvs update</command>.</para> + </sect3> + + <sect3> + <title><filename>pre-build.local</filename></title> + + <para>It is possible to configure the bulk build to perform certain site + specific tasks at the end of the pre-build stage. If the file + <filename>pre-build.local</filename> exists in + <filename>/usr/pkgsrc/mk/bulk</filename> it will be executed + (as a sh(1) script) at the end of the usual pre-build stage. An + example use of <filename>pre-build.local</filename> is to have the + line:</para> + + <screen>&rprompt; <userinput>echo "I do not have enough disk space to build this pig." \ + > pkgsrc/games/crafty-book-enormous/$BROKENF</userinput></screen> + + <para>to prevent the system from trying to build a particular package + which requires nearly 3 GB of disk space.</para> + </sect3> + </sect2> + + <sect2> + <title>Other environmental considerations</title> + + <para>As <filename>/usr/pkg</filename> will be completely deleted at the + start of bulk builds, make sure your login shell is placed somewhere + else. Either drop it into <filename>/usr/local/bin</filename> + (and adjust your login shell in the passwd file), or (re-)install + it via &man.pkg.add.1; from + <filename>/etc/rc.local</filename>, so you can login after a reboot + (remember that your current process won't die if the package is + removed, you just can't start any new instances of the shell any more). + Also, if you use &os; earlier than 1.5, or you still want to use the + pkgsrc version of ssh for some reason, be sure to install ssh before + starting it from <filename>rc.local</filename>:</para> + + <programlisting>( cd /usr/pkgsrc/security/ssh ; make bulk-install ) +if [ -f /usr/pkg/etc/rc.d/sshd ]; then + /usr/pkg/etc/rc.d/sshd +fi</programlisting> + + <para>Not doing so will result in you being not able to log in via ssh + after the bulk build is finished or if the machine gets rebooted + or crashes. You have been warned! :)</para> + </sect2> + + <sect2> + <title>Operation</title> + + <para>Make sure you don't need any of the packages still installed.</para> + + <warning> + <para>During the bulk build, <emphasis>all packages will be + removed!</emphasis></para> + </warning> + + <para>Be sure to remove all other things that might + interfere with builds, like some libs installed in + <filename>/usr/local</filename>, etc. then become root and type:</para> + + <screen>&rprompt; <userinput>cd /usr/pkgsrc</userinput> +&rprompt; <userinput>sh mk/bulk/build</userinput></screen> + + <para>If for some reason your last build didn't complete (power failure, + system panic, ...), you can continue it by running:</para> + + <screen>&rprompt; <userinput>sh mk/bulk/build restart</userinput></screen> + + <para>At the end of the bulk build, you will get a summary via mail, and find + build logs in the directory specified by <varname>FTP</varname> in the + <filename>build.conf</filename> file.</para> + </sect2> + + <sect2> + <title>What it does</title> + + <para>The bulk builds consist of three steps:</para> + + <variablelist> + <varlistentry> + <term>1. pre-build</term> + + <listitem> + <para>The script updates your pkgsrc tree via (anon)cvs, then cleans + out any broken distfiles, and removes all packages installed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>2. the bulk build</term> + + <listitem> + <para>This is basically + <quote>make bulk-package</quote> with an optimised + order in which packages will be built. Packages that don't require + other packages will be built first, and packages with many dependencies + will be built later.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>3. post-build</term> + + <listitem> + <para>Generates a report that's placed in the directory specified + in the <filename>build.conf</filename> file named + <filename>broken.html</filename>, a short version of + that report will also be mailed to the build's admin.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>During the build, a list of broken packages will be compiled in + <filename>/usr/pkgsrc/.broken</filename> (or + <filename>.../.broken.${MACHINE}</filename> if + <varname>OBJMACHINE</varname> is set), + individual build logs of broken builds can be found in the package's + directory. These files are used by the bulk-targets to mark broken builds + to not waste time trying to rebuild them, and they can be used to debug + these broken package builds later.</para> + </sect2> + + <sect2> + <title>Disk space requirements</title> + + <para>Currently, roughly the following requirements are valid for + NetBSD 2.0/i386:</para> + + <itemizedlist> + <listitem> + <para>10 GB - distfiles (NFS ok)</para> + </listitem> + + <listitem> + <para>8 GB - full set of all binaries (NFS ok)</para> + </listitem> + + <listitem> + <para>5 GB - temp space for compiling (local disk recommended)</para> + </listitem> + </itemizedlist> + + <para>Note that all pkgs will be de-installed as soon as they are turned into a + binary package, and that sources are removed, so there is no excessively huge + demand to disk space. Afterwards, if the package is needed again, it will + be installed via &man.pkg.add.1; instead of building again, so + there are no cycles wasted by recompiling.</para> + </sect2> + + <sect2> + <title>Setting up a sandbox for chroot'ed builds</title> + + <para>If you don't want all the pkgs nuked from a machine (rendering it useless + for anything but pkg compiling), there is the possibility of doing the pkg + bulk build inside a chroot environment.</para> + + <para>The first step to do so is setting up a chroot + sandbox, e.g. <filename>/usr/sandbox</filename>. + After extracting all the sets from a &os; installation or doing a + <command>make distribution DESTDIR=/usr/sandbox</command> in + <filename>/usr/src/etc</filename>, be sure the following + items are present and properly configured:</para> + + <procedure> + <step> + <para>Kernel</para> + + <screen>&rprompt; <userinput>cp /netbsd /usr/sandbox</userinput></screen> + </step> + + <step> + <para><filename>/dev/*</filename></para> + + <screen>&rprompt; <userinput>cd /usr/sandbox/dev ; sh MAKEDEV all</userinput></screen> + </step> + + <step> + <para><filename>/etc/resolv.conf</filename> (for <pkg>security/smtpd</pkg> and mail):</para> + + <screen>&rprompt; <userinput>cp /etc/resolv.conf /usr/sandbox/etc</userinput></screen> + </step> + + <step> + <para>Working(!) mail config (hostname, sendmail.cf):</para> + + <screen>&rprompt; <userinput>cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail</userinput></screen> + </step> + + <step> + <para><filename>/etc/localtime</filename> (for <pkg>security/smtpd</pkg>):</para> + + <screen>&rprompt; <userinput>ln -sf /usr/share/zoneinfo/UTC /usr/sandbox/etc/localtime</userinput></screen> + </step> + + <step> + <para><filename>/usr/src</filename> (system sources, for <pkg>sysutils/aperture</pkg>, + <pkg>net/ppp-mppe</pkg>):</para> + + <screen>&rprompt; <userinput>ln -s ../disk1/cvs .</userinput> +&rprompt; <userinput>ln -s cvs/src-1.6 src</userinput></screen> + </step> + + <step> + <para>Create <filename>/var/db/pkg</filename> (not part of default install):</para> + + <screen>&rprompt; <userinput>mkdir /usr/sandbox/var/db/pkg</userinput></screen> + </step> + + <step> + <para>Create <filename>/usr/pkg</filename> (not part of default install):</para> + + <screen>&rprompt; <userinput>mkdir /usr/sandbox/usr/pkg</userinput></screen> + </step> + + <step> + <para>Checkout pkgsrc via cvs into + <filename>/usr/sandbox/usr/pkgsrc</filename>:</para> + + <screen>&rprompt; <userinput>cd /usr/sandbox/usr</userinput> +&rprompt; <userinput>cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -d -P pkgsrc</userinput></screen> + + <para>Do not mount/link this to the copy of your pkgsrc tree + you do development in, as this will likely cause problems! + </para> + </step> + + <step> + <para>Make + <filename>/usr/sandbox/usr/pkgsrc/packages</filename> and + <filename>.../distfiles</filename> point somewhere + appropriate. NFS- and/or nullfs-mounts may come in handy! + </para> + </step> + + <step> + <para>Edit <filename>/etc/mk.conf</filename>, see <xref linkend="binary.mk.conf"/>.</para> + </step> + + <step> + <para>Adjust <filename>mk/bulk/build.conf</filename> to suit your needs.</para> + </step> + + <step> + <para>If you have set <varname>CVS_USER</varname> in + <filename>build.conf</filename>, make sure that + account exists and can do a <command>cvs ${CVS_FLAGS} + update</command> properly!</para> + </step> + </procedure> + + <para>When the chroot sandbox is setup, you can start + the build with the following steps:</para> + + <screen>&rprompt; <userinput>cd /usr/sandbox/usr/pkgsrc</userinput> +&rprompt; <userinput>sh mk/bulk/do-sandbox-build</userinput></screen> + + <para>This will just jump inside the sandbox and start building. + At the end of the build, mail will be sent with the results of the build. + Created binary pkgs will be in + <filename>/usr/sandbox/usr/pkgsrc/packages</filename> (wherever + that points/mounts to/from).</para> + </sect2> + + <sect2> + <title>Building a partial set of packages</title> + + <para> In addition to building a complete set of all packages in + pkgsrc, the <filename>pkgsrc/mk/bulk/build</filename> script + may be used to build a subset of the packages contained in + pkgsrc. By setting defining <varname>SPECIFIC_PKGS</varname> + in <filename>/etc/mk.conf</filename>, the variables</para> + + <itemizedlist> + <listitem><para>SITE_SPECIFIC_PKGS</para></listitem> + <listitem><para>HOST_SPECIFIC_PKGS</para></listitem> + <listitem><para>GROUP_SPECIFIC_PKGS</para></listitem> + <listitem><para>USER_SPECIFIC_PKGS</para></listitem> + </itemizedlist> + + <para> will define the set of packages which should be built. + The bulk build code will also include any packages which are + needed as dependencies for the explicitly listed packages. + </para> + + <para> One use of this is to do a bulk build with + <varname>SPECIFIC_PKGS</varname> in a chroot sandbox + periodically to have a complete set of the binary packages + needed for your site available without the overhead of + building extra packages that are not needed. </para> + + </sect2> + </sect1> + + <sect1> + <title>Creating a multiple CD-ROM packages collection</title> + + <para>After your pkgsrc bulk-build has completed, you may wish to create a CD-ROM + set of the resulting binary packages to assist in installing packages on + other machines. The <pkg>pkgtools/cdpack</pkg> package provides a simple + tool for creating the ISO 9660 images. <command>cdpack</command> arranges + the packages on the CD-ROMs in a way that keeps all the dependencies for + given package on the same CD as that package.</para> + + <sect2> + <title>Example of cdpack</title> + + <para>Complete documentation for cdpack is found in the + cdpack(1) manpage. The following + short example assumes that the binary packages are left in + <filename>/usr/pkgsrc/packages/All</filename> and that sufficient disk + space exists in <filename>/u2</filename> to hold the ISO 9660 images.</para> + + <screen>&rprompt; <userinput>mkdir /u2/images</userinput> +&rprompt; <userinput>pkg_add /usr/pkgsrc/packages/All/cdpack</userinput> +&rprompt; <userinput>cdpack /usr/pkgsrc/packages/All /u2/images</userinput></screen> + + <para>If you wish to include a common set of files + (<filename>COPYRIGHT</filename>, <filename>README</filename>, etc.) + on each CD in the collection, then you need to create a directory which + contains these files. e.g.</para> + + <screen>&rprompt; <userinput>mkdir /tmp/common</userinput> +&rprompt; <userinput>echo "This is a README" > /tmp/common/README</userinput> +&rprompt; <userinput>echo "Another file" > /tmp/common/COPYING</userinput> +&rprompt; <userinput>mkdir /tmp/common/bin</userinput> +&rprompt; <userinput>echo "#!/bin/sh" > /tmp/common/bin/myscript</userinput> +&rprompt; <userinput>echo "echo Hello world" >> /tmp/common/bin/myscript</userinput> +&rprompt; <userinput>chmod 755 /tmp/common/bin/myscript</userinput></screen> + + <para>Now create the images:</para> + + <screen>&rprompt; <userinput>cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images</userinput></screen> + + <para>Each image will contain <filename>README</filename>, + <filename>COPYING</filename>, and <filename>bin/myscript</filename> + in their root directories.</para> + </sect2> + </sect1> +</chapter> diff --git a/doc/guide/files/build.xml b/doc/guide/files/build.xml new file mode 100644 index 00000000000..d79c4a1a45e --- /dev/null +++ b/doc/guide/files/build.xml @@ -0,0 +1,710 @@ +<!-- $NetBSD: build.xml,v 1.1.1.1 2004/10/21 14:27:38 grant Exp $ --> + +<chapter id="build"> + <title>The build process</title> + + <para>The basic steps for building a program are always the same. First the + program's source (<emphasis>distfile</emphasis>) must be brought to the + local system and then extracted. After any patches to compile properly + on &os; are applied, the software can be configured, then built + (usually by compiling), and finally the generated binaries, etc. can be + put into place on the system. These are exactly the steps performed by + the &os; package system, which is implemented as a series of targets + in a central Makefile, <filename>pkgsrc/mk/bsd.pkg.mk</filename>.</para> + + <sect1 id="build.prefix"> + <title>Program location</title> + + <para>Before outlining the process performed by the &os; package system in + the next section, here's a brief discussion on where programs are + installed, and which variables influence this.</para> + + <para>The automatic variable <varname>PREFIX</varname> indicates + where all files of the final program shall be installed. It is + usually set to <varname>LOCALBASE</varname> + (<filename>/usr/pkg</filename>), or <varname>CROSSBASE</varname> + for pkgs in the <quote>cross</quote> category. The value of + <varname>PREFIX</varname> needs to be put + into the various places in the program's source where paths to + these files are encoded. See <xref + linkend="components.patches"/> and <xref + linkend="fixes.libtool"/> for more details.</para> + + <para>When choosing which of these variables to use, + follow the following rules:</para> + + <itemizedlist> + <listitem> + <para><varname>PREFIX</varname> always points to the location where the current + pkg will be installed. When referring to a pkg's own installation path, + use <quote>${PREFIX}</quote>.</para> + </listitem> + + <listitem> + <para><varname>LOCALBASE</varname> is where all non-X11 pkgs are installed. + If you need to construct a -I or -L argument to the compiler to find + includes and libraries installed by another non-X11 pkg, use + <quote>${LOCALBASE}</quote>.</para> + </listitem> + + <listitem> + <para><varname>X11BASE</varname> is where the actual X11 distribution (from + xsrc, etc.) is installed. When looking for + <emphasis>standard</emphasis> X11 includes (not + those installed by a pkg), use <quote>${X11BASE}</quote>.</para> + </listitem> + + <listitem> + <para>X11 based are special in that they may be installed in either + <varname>X11BASE</varname> or <varname>LOCALBASE</varname>.</para> + + <para>Usually, X11 packages should be installed under + <varname>LOCALBASE</varname> whenever possible. Note that you will + need to set <varname>USE_X11</varname> in them to request the + presence of X11 and to get the right compilation flags.</para> + + <para>Even though, there are some packages that cannot be installed + under <varname>LOCALBASE</varname>: those that come with app-defaults + files. These packages are special and they must be placed under + <varname>X11BASE</varname>. To accomplish this, set either + <varname>USE_X11BASE</varname> or <varname>USE_IMAKE</varname> in + your package.</para> + + <para>Some notes: <varname>USE_X11</varname> and + <varname>USE_X11BASE</varname> are mutually exclusive. If you need + to find includes or libraries installed by a pkg that has + <varname>USE_IMAKE</varname> or <varname>USE_X11BASE</varname> in + its pkg <filename>Makefile</filename>, you need to use + <emphasis>both</emphasis> <filename>${X11BASE}</filename> and + <filename>${LOCALBASE}</filename>. To force installation of + all X11 packages in <varname>LOCALBASE</varname>, the + <pkg>pkgtools/xpkgwedge</pkg> is enabled by default.</para> + </listitem> + + <listitem> + <para><varname>X11PREFIX</varname> should be used to refer to the installed + location of an X11 package. <varname>X11PREFIX</varname> will be set to + <varname>X11BASE</varname> if xpkgwedge is not installed, + and to <varname>LOCALBASE</varname> if xpkgwedge is installed.</para> + </listitem> + + <listitem> + <para>If xpkgwedge is installed, it is possible to have some packages installed + in <varname>X11BASE</varname> and some in <varname>LOCALBASE</varname>. + To determine the prefix of an installed package, the + <varname>EVAL_PREFIX</varname> definition can be used. It takes pairs in the + format <quote>DIRNAME=<package></quote>, and the make(1) variable + <varname>DIRNAME</varname> will be set to the prefix of the installed + package <package>, or <quote>${X11PREFIX}</quote> if the package is + not installed.</para> + + <para>This is best illustrated by example.</para> + + <para>The following lines are taken from + <filename>pkgsrc/wm/scwm/Makefile</filename>:</para> + + <programlisting>EVAL_PREFIX+= GTKDIR=gtk+ +CONFIGURE_ARGS+= --with-guile-prefix=${LOCALBASE} \ + --with-gtk-prefix="${GTKDIR}" \ + --enable-multibyte</programlisting> + + <para>Specific defaults can be defined for the packages evaluated using + <varname>EVAL_PREFIX</varname>, by using a definition of the form:</para> + + <programlisting>GTKDIR_DEFAULT= ${LOCALBASE}</programlisting> + + <para>where <varname>GTKDIR</varname> corresponds + to the first definition in + the <varname>EVAL_PREFIX</varname> pair.</para> + </listitem> + + <listitem> + <para>Within <filename>${PREFIX}</filename>, packages should + install files according to hier(7), with the exception that + manual pages go into <filename>${PREFIX}/man</filename>, not + <filename>${PREFIX}/share/man</filename>.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Main targets</title> + + <para>The main targets used during the build process defined in + <filename>bsd.pkg.mk</filename> are:</para> + + <variablelist> + <varlistentry> + <term>fetch</term> + + <listitem> + <para>This will check if the file(s) given in the variables + <varname>DISTFILES</varname> and <varname>PATCHFILES</varname> (as + defined in the package's Makefile) are present on the + local system in <filename>/usr/pkgsrc/distfiles</filename>. If they + are not present, an attempt will be made to fetch them using commands + of the form:</para> + + <programlisting>${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}</programlisting> + + <para>where ${site} varies through several possibilities in turn: first, + <varname>MASTER_SITE_OVERRIDE</varname> is tried, then the sites + specified in either <varname>SITES_file</varname> if defined, else + <varname>MASTER_SITES</varname> or <varname>PATCH_SITES</varname>, as + applies, then finally the value of + <varname>MASTER_SITE_BACKUP</varname>. The order of all except the + first can be optionally sorted by the user, via setting either + <varname>MASTER_SORT_AWK</varname> or + <varname>MASTER_SORT_REGEX</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>checksum</term> + + <listitem> + <para>After the distfile(s) are fetched, their checksum is generated and + compared with the checksums stored in the distinfo file. If the + checksums don't match, the build is aborted. This is to ensure the same + distfile is used for building, and that the distfile wasn't changed, + e.g. by some malign force, deliberately changed distfiles on the master + distribution site or network lossage.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>extract</term> + + <listitem> + <para>When the distfiles are present on the local system, + they need to be extracted, as they are usually in the form + of some compressed archive format, most commonly + <filename>.tar.gz</filename>. </para> + + <para> If only some of the + distfiles need to be uncompressed, the files to be + uncompressed should be put into + <varname>EXTRACT_ONLY</varname>.</para> + + <para> If the distfiles are not in + <filename>.tar.gz</filename> format, they can be extracted + by setting either <varname>EXTRACT_SUFX</varname>, or + <varname>EXTRACT_CMD</varname>, + <varname>EXTRACT_BEFORE_ARGS</varname> and + <varname>EXTRACT_AFTER_ARGS</varname>. In the former case, + pkgsrc knows how to extract a number of suffixes + (<filename>.tar.gz</filename>, <filename>.tgz</filename>, + <filename>.tar.gz2</filename>, <filename>.tbz</filename>, + <filename>.tar.Z</filename>, <filename>.tar</filename>, + <filename>.shar.gz</filename>, + <filename>.shar.bz2</filename>, + <filename>.shar.Z</filename>, <filename>.shar</filename>, + <filename>.Z</filename>, <filename>.bz2</filename> and + <filename>.gz</filename>; see the definition of the + various <varname>DECOMPRESS_CMD</varname> variables + <filename>bsd.pkg.mk</filename> for a complete + list). Here's an example on how to use the other variables + for a program that comes with a compressed shell archive + whose name ends in <filename>.msg.gz</filename>:</para> + + <programlisting> EXTRACT_SUFX= .msg.gz + EXTRACT_CMD= zcat + EXTRACT_BEFORE_ARGS= + EXTRACT_AFTER_ARGS= |sh</programlisting> + </listitem> + </varlistentry> + + <varlistentry> + <term>patch</term> + + <listitem> + <para>After extraction, all the patches named by the + <varname>PATCHFILES</varname>, those present in the patches + subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g. + <filename>/usr/local/patches/graphics/png</filename>) are applied. + Patchfiles ending in <filename>.Z</filename> or + <filename>.gz</filename> are uncompressed before they are applied, + files ending in <filename>.orig</filename> or + <filename>.rej</filename> are ignored. Any special options to patch(1) + can be handed in <varname>PATCH_DIST_ARGS</varname>. + See <xref linkend="components.patches"/> for more details.</para> + + <para>By default patch(1) is given special args to make it fail if the + patches apply with some lines of fuzz. Please fix (regen) the patches + so that they apply cleanly. The rationale behind this is that + patches that don't apply cleanly may end up being applied in the wrong + place, and cause severe harm there.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>configure</term> + + <listitem> + <para>Most pieces of software need information on the header files, + system calls, and library routines which are available in &os;. + This is the process known as configuration, and is usually + automated. In most cases, a script is supplied with the source, + and its invocation results in generation of header files, + Makefiles, etc.</para> + + <para>If the program's distfile contains its own configure + script, this can be invoked by setting + <varname>HAS_CONFIGURE</varname>. If the configure script + is a GNU autoconf script, <varname>GNU_CONFIGURE</varname> + should be specified instead. In either case, any arguments + to the configure script can be specified in the + <varname>CONFIGURE_ARGS</varname> variable, and the + configure script's name can be set in + <varname>CONFIGURE_SCRIPT</varname> if it differs from the + default <quote>configure</quote>. Here's an example from + the <pkg>sysutils/top</pkg> package:</para> + + <programlisting>HAS_CONFIGURE= yes +CONFIGURE_SCRIPT= Configure +CONFIGURE_ARGS+= netbsd13</programlisting> + + <para>If the program uses an Imakefile for configuration, the appropriate + steps can be invoked by setting <varname>USE_IMAKE</varname> to + <quote>YES</quote>. (If you only want the package installed in + <varname>$X11PREFIX</varname> but xmkmf not being run, set + <varname>USE_X11BASE</varname> instead!)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>build</term> + + <listitem> + <para>Once configuration has taken place, the software will be built + by invoking <varname>$MAKE_PROGRAM</varname> on + <varname>$MAKEFILE</varname> with <varname>$ALL_TARGET</varname> as + the target to build. The default <varname>MAKE_PROGRAM</varname> is + <quote>gmake</quote> if <varname>USE_GMAKE</varname> is set, + <quote>make</quote> otherwise. <varname>MAKEFILE</varname> is set to + <quote>Makefile</quote> by default, and <varname>ALL_TARGET</varname> + defaults to <quote>all</quote>. Any of these variables + can be set in the package's Makefile to change the default + build process.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>install</term> + + <listitem> + <para>Once the build stage has completed, the final step is to install + the software in public directories, so users can access + the programs and files. As in the + build-target, <varname>$MAKE_PROGRAM</varname> is invoked on + <varname>$MAKEFILE</varname> here, but with the + <varname>$INSTALL_TARGET</varname> instead, the latter defaulting to + <quote>install</quote> (plus <quote>install.man</quote>, if + <varname>USE_IMAKE</varname> is set).</para> + </listitem> + </varlistentry> + </variablelist> + + <para>If no target is specified, the default is <quote>build</quote>. + If a subsequent stage is requested, all prior stages are made: e.g. + <command>make build</command> will also perform the equivalent of:</para> + + <programlisting> +make fetch +make checksum +make extract +make patch +make configure +make build</programlisting> + </sect1> + + <sect1 id="build.helpful-targets"> + <title>Other helpful targets</title> + + <variablelist> + <varlistentry> + <term>pre/post-*</term> + + <listitem> + <para>For any of the main targets described in the previous section, two + auxiliary targets exist with <quote>pre-</quote> and + <quote>post-</quote> used as a prefix + for the main target's name. These targets are invoked before and + after the main target is called, allowing extra configuration or + installation steps be performed from a package's Makefile, for + example, which a program's configure script + or install target omitted.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>do-*</term> + + <listitem> + <para>Should one of the main targets do the wrong thing, and should there + be no variable to fix this, you can redefine it with the do-* + target. (Note that redefining the target itself instead of the + do-* target is a bad idea, as the pre-* and post-* targets won't be + called anymore, etc.) You will not usually need to do this.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>reinstall</term> + + <listitem> + <para>If you did a <command>make install</command> and you noticed some file + was not installed properly, you can repeat the installation with this + target, which will ignore the <quote>already installed</quote> flag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>deinstall</term> + + <listitem> + <para>This target does a pkg_delete(1) in the current directory, + effectively de-installing the package. The following variables can + be used to tune the behaviour:</para> + + <variablelist> + <varlistentry> + <term><varname>PKG_VERBOSE</varname></term> + + <listitem> + <para>Add a "-v" to the &man.pkg.delete.1; command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DEINSTALLDEPENDS</varname></term> + + <listitem> + <para>Remove all packages that require (depend on) the given package. + This can be used to remove any packages that may have been pulled in + by a given package, e.g. if <command>make deinstall + DEINSTALLDEPENDS=1</command> is done in + <filename>pkgsrc/x11/kde</filename>, this is likely to remove whole + KDE. Works by adding <quote>-R</quote> to the &man.pkg.delete.1; command line.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>update</term> + + <listitem> + <para>This target causes the current package to be updated to the latest + version. The package and all depending packages first get de-installed, + then current versions of the corresponding packages get compiled and + installed. This is similar to manually noting which packages are + currently installed, then performing a series of <command>make + deinstall</command> and <command>make install</command> (or whatever + <varname>UPDATE_TARGET</varname> is set to) for these packages.</para> + + <para>You can use the <quote>update</quote> target to resume package + updating in case a previous <command>make update</command> was interrupted + for some reason. However, in this case, make sure you don't call + <command>make clean</command> or otherwise remove the list of dependent + packages in <varname>WRKDIR</varname>. Otherwise you lose the + ability to automatically update the current package along with the + dependent packages you have installed.</para> + + <para>Resuming an interrupted <command>make update</command> will only work as + long as the package tree remains unchanged. If the source code for + one of the packages to be updated has been changed, resuming + <command>make update</command> will most certainly fail!</para> + + <para>The following variables can be used either on the command line or in + <filename>/etc/mk.conf</filename> to alter the behaviour of + <command>make update</command>:</para> + + <variablelist> + <varlistentry> + <term><varname>UPDATE_TARGET</varname></term> + + <listitem> + <para>Install target to recursively use for the updated package and the + dependent packages. Defaults to <varname>DEPENDS_TARGET</varname> if set, + <quote>install</quote> otherwise for <command>make update</command>. + e.g. <command>make update UPDATE_TARGET=package</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>NOCLEAN</varname></term> + + <listitem> + <para>Don't clean up after updating. Useful if you want to leave the + work sources of the updated packages around for inspection or + other purposes. Be sure you eventually clean up the source + tree (see the <quote>clean-update</quote> target below) or you may + run into troubles with old source code still lying around on your + next <command>make</command> or <command>make update</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>REINSTALL</varname></term> + + <listitem> + <para>Deinstall each package before installing (making + <varname>DEPENDS_TARGET</varname>). This may be necessary if the + <quote>clean-update</quote> target (see below) was called after + interrupting a running <command>make update</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DEPENDS_TARGET</varname></term> + + <listitem> + <para>Allows you to disable recursion and hardcode the target for + packages. The default is <quote>update</quote> for the update target, + facilitating a recursive update of prerequisite packages. + Only set <varname>DEPENDS_TARGET</varname> if you want to disable + recursive updates. Use <varname>UPDATE_TARGET</varname> instead to just + set a specific target for each package to be installed during + <command>make update</command> (see above).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>clean-update</term> + + <listitem> + <para>Clean the source tree for all packages that would get updated if + <command>make update</command> was called from the current directory. + This target should not be used if the current package (or any of its + depending packages) have already been de-installed (e.g., after calling + <command>make update</command>) or you may lose some packages you intended + to update. As a rule of thumb: only use this target + <emphasis>before</emphasis> the first time you run + <command>make update</command> and only if you have a dirty package tree + (e.g., if you used <varname>NOCLEAN</varname>).</para> + + <para>If you unsure about whether your tree is clean you can either perform + a <command>make clean</command> at the top of the tree, or use the + following sequence of commands from the directory of the package you + want to update (<emphasis>before</emphasis> running + <command>make update</command> for the first time, otherwise you lose + all the packages you wanted to update!):</para> + + <screen><prompt>#</prompt> <userinput>make clean-update</userinput> +<prompt>#</prompt> <userinput>make clean CLEANDEPENDS=YES</userinput> +<prompt>#</prompt> <userinput>make update</userinput></screen> + + <para>The following variables can be used either on the command line or in + <filename>/etc/mk.conf</filename> to alter the behaviour of + <command>make clean-update</command>:</para> + + <variablelist> + <varlistentry> + <term><varname>CLEAR_DIRLIST</varname></term> + + <listitem> + <para>After <command>make clean</command>, do not reconstruct the list of + directories to update for this package. Only use this if <command>make + update</command> successfully installed all packages you wanted to + update. Normally, this is done automatically on <command>make + update</command>, but may have been suppressed by the + <varname>NOCLEAN</varname> variable (see above).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>info</term> + + <listitem> + <para>This target invokes &man.pkg.info.1; for the current + package. You can use this to check which version of a package is + installed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>readme</term> + + <listitem> + <para>This target generates a <filename>README.html</filename> file, which + can be viewed using a browser such as <pkg>www/mozilla</pkg> or + <pkg>www/links</pkg>. The generated files contain references to any + packages which are in the <varname>PACKAGES</varname> directory on + the local host. The generated files can be made to refer to URLs based on + <varname>FTP_PKG_URL_HOST</varname> and + <varname>FTP_PKG_URL_DIR</varname>. For example, if I wanted to generate + <filename>README.html</filename> files which pointed to binary packages + on the local machine, in the directory + <filename>/usr/packages</filename>, set + <varname>FTP_PKG_URL_HOST=file://localhost</varname> and + <varname>FTP_PKG_URL_DIR=/usr/packages</varname>. The + <varname>${PACKAGES}</varname> directory and its subdirectories will be + searched for all the binary packages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>readme-all</term> + + <listitem> + <para>Use this target to create a file <filename>README-all.html</filename> + which contains a list of all packages currently available in the &os; + Packages Collection, together with the category they belong to and a + short description. This file is compiled from the + <filename>pkgsrc/*/README.html</filename> files, so be sure to run + this <emphasis>after</emphasis> a <command>make readme</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cdrom-readme</term> + + <listitem> + <para>This is very much the same as the <quote>readme</quote> target (see + above), but is to be used when generating a pkgsrc tree to be written + to a CD-ROM. This target also produces + <filename>README.html</filename> files, and can be made to refer + to URLs based on <varname>CDROM_PKG_URL_HOST</varname> and + <varname>CDROM_PKG_URL_DIR</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>show-distfiles</term> + + <listitem> + <para>This target shows which distfiles and patchfiles are needed to build + the package. (<varname>DISTFILES</varname> and + <varname>PATCHFILES</varname>, but not <filename>patches/*</filename>)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>show-downlevel</term> + + <listitem> + <para>This target shows nothing if the package is not installed. If a version + of this package is installed, but is not the version provided in this + version of pkgsrc, then a warning message is displayed. This target can + be used to show which of your installed packages are downlevel, and so + the old versions can be deleted, and the current ones added.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>show-pkgsrc-dir</term> + + <listitem> + <para>This target shows the directory in the pkgsrc hierarchy from which the + package can be built and installed. This may not be the same directory + as the one from which the package was installed. This target is intended + to be used by people who may wish to upgrade many packages on a single + host, and can be invoked from the top-level pkgsrc Makefile by using the + <quote>show-host-specific-pkgs</quote> target.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>show-installed-depends</term> + + <listitem> + <para>This target shows which installed packages match the current package's + <varname>DEPENDS</varname>. Useful if out of date dependencies are + causing build problems.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>check-shlibs</term> + + <listitem> + <para>After a package is installed, check all its binaries and (on ELF + platforms) shared libraries to see if they find the shared libs they need. + Run by default if <varname>PKG_DEVELOPER</varname> is set in + <filename>/etc/mk.conf</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>print-PLIST</term> + + <listitem> + <para>After a <quote>make install</quote> from a new or + upgraded pkg, this prints out an attempt to generate a new + <filename>PLIST</filename> from a <command>find -newer + work/.extract_done</command>. An attempt is made to care + for shared libs etc., but it is + <emphasis>strongly</emphasis> recommended to review the + result before putting it into + <filename>PLIST</filename>. On upgrades, it's useful to + diff the output of this command against an already + existing <filename>PLIST</filename> file.</para> + + <para>If the package installs files via tar(1) or other + methods that don't update file access times, be sure to + add these files manually to your + <filename>PLIST</filename>, as the <quote>find + -newer</quote> command used by this target won't catch + them!</para> + + <para> See <xref linkend="print-PLIST"/> for more + information on this target.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bulk-package</term> + + <listitem> + <para>Used to do bulk builds. If an appropriate binary package already exists, + no action is taken. If not, this target will compile, install and + package it (and it's depends, if <varname>PKG_DEPENDS</varname> is + set properly. See <xref linkend="binary.configuration"/>. + After creating the binary + package, the sources, the just-installed package and it's required + packages are removed, preserving free disk space.</para> + + <para><emphasis>Beware that this target may deinstall all + packages installed on a system!</emphasis></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bulk-install</term> + + <listitem> + <para>Used during bulk-installs to install required packages. If an + upto-date binary package is available, it will be installed via + &man.pkg.add.1;. If not, <command>make bulk-package</command> will be executed, + but the installed binary not be removed. </para> + + <para> A binary package is considered <quote>upto-date</quote> to be + installed via &man.pkg.add.1; if:</para> + + <itemizedlist> + <listitem> + <para>None of the package's files (<filename>Makefile</filename>, + ...) were modified since it was built.</para> + </listitem> + + <listitem> + <para>None of the package's required (binary) packages were + modified since it was built.</para> + </listitem> + </itemizedlist> + + <para><emphasis>Beware that this target may deinstall all + packages installed on a system!</emphasis></para> + </listitem> + </varlistentry> + </variablelist> + </sect1> +</chapter> diff --git a/doc/guide/files/buildlink.xml b/doc/guide/files/buildlink.xml new file mode 100644 index 00000000000..23bb741e203 --- /dev/null +++ b/doc/guide/files/buildlink.xml @@ -0,0 +1,571 @@ +<!-- $NetBSD: buildlink.xml,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ --> + +<chapter id="buildlink"> + <title>Buildlink methodology</title> + + <para>Buildlink is a framework in pkgsrc that controls what headers and libraries + are seen by a package's configure and build processes. This is implemented + in a two step process:</para> + + <orderedlist> + <listitem> + <para>Symlink headers and libraries for dependencies into + <varname>BUILDLINK_DIR</varname>, which by default is a subdirectory + of <varname>WRKDIR</varname>.</para> + </listitem> + + <listitem> + <para>Create wrapper scripts that are used in place of the normal compiler + tools that translate <option>-I${LOCALBASE}/include</option> and + <option>-L${LOCALBASE}/lib</option> into references to + <varname>BUILDLINK_DIR</varname>. The wrapper scripts also make + native compiler on some operating systems look like GCC, so that + packages that expect GCC won't require modifications to build with + those native compilers.</para> + </listitem> + </orderedlist> + + <para>This normalizes the environment in which a package is built so that the + package may be built consistently despite what other software may be + installed. Please note that the normal system header and library paths, + e.g. <filename>/usr/include</filename>, + <filename>/usr/lib</filename>, etc., are always searched -- buildlink3 is + designed to insulate the package build from non-system-supplied + software. </para> + + <sect1> + <title>Converting packages to use buildlink3</title> + + <para>The process of converting packages to use the buildlink3 + framework (<quote>bl3ifying</quote>) is fairly straightforward. + The things to keep in mind are:</para> + + <orderedlist> + <listitem> + <para>Set <varname>USE_BUILDLINK3</varname> to + <quote>yes</quote>.</para> + </listitem> + + <listitem> + <para> Ensure that the build always calls the wrapper scripts + instead of the actual toolchain. Some packages are tricky, + and the only way to know for sure is the check + <filename>${WRKDIR}/.work.log</filename> to see if the + wrappers are being invoked. </para> + </listitem> + + <listitem> + <para> Don't override <varname>PREFIX</varname> from within + the package Makefile, e.g. Java VMs, standalone shells, + etc., because the code to symlink files into + <filename>${BUILDLINK_DIR}</filename> looks for files + relative to <quote>pkg_info -qp <replaceable>pkgname</replaceable></quote>. + </para> + </listitem> + + <listitem> + <para> Remember that <emphasis>only</emphasis> the + <filename>buildlink3.mk</filename> files that you list in a + package's Makefile are added as dependencies for that package. + </para> + </listitem> + </orderedlist> + + <para> If a dependency on a particular package is required for its libraries and + headers, then we replace: </para> + + <programlisting>DEPENDS+= foo>=1.1.0:../../category/foo</programlisting> + + <para>with</para> + + <programlisting>.include "../../category/foo/buildlink3.mk"</programlisting> + + <para>There are several <filename>buildlink3.mk</filename> + files in <filename>pkgsrc/mk</filename> + that handle special package issues:</para> + + <itemizedlist> + <listitem> + <para><filename>bdb.buildlink3.mk</filename> chooses either + the native or a pkgsrc Berkeley DB implementation based on + the values of <varname>BDB_ACCEPTED</varname> and + <varname>BDB_DEFAULT</varname>.</para> + </listitem> + + <listitem> + <para><filename>curses.buildlink3.mk</filename> If the system + comes with neither Curses nor NCurses, this will take care + to install the <pkg>devel/ncurses</pkg> package.</para> + </listitem> + + <listitem> + <para><filename>krb5.buildlink3.mk</filename> uses the value + of <varname>KRB5_ACCEPTED</varname> to choose between + adding a dependency on Heimdal or MIT-krb5 for packages that + require a Kerberos 5 implementation.</para> + </listitem> + + <listitem> + <para><filename>motif.buildlink3.mk</filename> checks + for a system-provided + Motif installation or adds a dependency on <pkg>x11/lesstif</pkg> or + <pkg>x11/openmotif</pkg>;</para> + </listitem> + + <listitem> + <para><filename>ossaudio.buildlink3.mk</filename> defines several + variables that may be used by packages that use the + Open Sound System (OSS) API;</para> + </listitem> + + <listitem> + <para><filename>pgsql.buildlink3.mk</filename> will accept + either Postgres 7.3 or 7.4, whichever is found installed. See + the file for more information. </para> + </listitem> + + <listitem> + <para><filename>pthread.buildlink3.mk</filename> uses the value of + <varname>PTHREAD_OPTS</varname> and checks for native pthreads or adds + a dependency on <pkg>devel/pth</pkg> as needed;</para> + </listitem> + + <listitem> + <para><filename>xaw.buildlink3.mk</filename> uses the value of + <varname>XAW_TYPE</varname> to choose a particular Athena widgets + library.</para> + </listitem> + </itemizedlist> + + <para>The comments in those <filename>buildlink3.mk</filename> + files provide a more complete + description of how to use them properly.</para> + </sect1> + + <sect1> + <title>Writing <filename>buildlink3.mk</filename> files</title> + + <para> A package's <filename>buildlink3.mk</filename> file is + included by Makefiles to indicate the need to compile and link + against header files and libraries provided by the package. A + <filename>buildlink3.mk</filename> file should always provide + enough information to add the correct type of dependency + relationship and include any other + <filename>buildlink3.mk</filename> files that it needs to find + headers and libraries that it needs in turn.</para> + + <para> To generate an initial <filename>buildlink3.mk</filename> + file for further editing, Rene Hexel's <pkg>pkgtools/createbuildlink</pkg> + package is highly recommended. For most packages, the following + command will generate a good starting point for + <filename>buildlink3.mk</filename> files:</para> + + <screen>&cprompt; <userinput>cd pkgsrc/<replaceable>category</replaceable>/<replaceable>pkgdir</replaceable> +&cprompt; createbuildlink -3 >buildlink3.mk</userinput></screen> + + <sect2> + <title>Anatomy of a buildlink3.mk file</title> + + <para>The following real-life example + <filename>buildlink3.mk</filename> is taken + from <filename>pkgsrc/graphics/tiff</filename>:</para> + + <programlisting> +# $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $ + +BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH}+ +TIFF_BUILDLINK3_MK:= ${TIFF_BUILDLINK3_MK}+ + +.if !empty(BUILDLINK_DEPTH:M+) +BUILDLINK_DEPENDS+= tiff +.endif + +BUILDLINK_PACKAGES:= ${BUILDLINK_PACKAGES:Ntiff} +BUILDLINK_PACKAGES+= tiff + +.if !empty(TIFF_BUILDLINK3_MK:M+) +BUILDLINK_DEPENDS.tiff+= tiff>=3.6.1 +BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff +.endif # TIFF_BUILDLINK3_MK + +.include "../../devel/zlib/buildlink3.mk" +.include "../../graphics/jpeg/buildlink3.mk" + +BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH:S/+$//} </programlisting> + + <para> The header and footer manipulate + <varname>BUILDLINK_DEPTH</varname>, which is common across all + <filename>buildlink3.mk</filename> files and is used to track + at what depth we are including + <filename>buildlink3.mk</filename> files.</para> + + <para> The first section controls if the dependency on + <replaceable>pkg</replaceable> is added. + <varname>BUILDLINK_DEPENDS</varname> is the global list of + packages for which dependencies are added by + buildlink3.</para> + + <para> The second section advises pkgsrc that the + <filename>buildlink3.mk</filename> file for + <replaceable>pkg</replaceable> has been included at some point. + <varname>BUILDLINK_PACKAGES</varname> is the global list of + packages for which <filename>buildlink3.mk</filename> files + have been included. It must <emphasis>always</emphasis> be + appended to within a <filename>buildlink3.mk</filename> + file. </para> + + <para> The third section is protected from multiple inclusion + and controls how the dependency on <replaceable>pkg</replaceable> is + added. Several important variables are set in the section: + </para> + + <itemizedlist> + <listitem> + <para> <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> + is the actual dependency recorded in the installed + package; this should always be set using + <command>+=</command> to ensure that + we're appending to any pre-existing list of values. This + variable should be set to the first version of the + package that had the last change in the major number of a + shared library or that had a major API change. + </para> + </listitem> + + <listitem> + <para> <varname>BUILDLINK_PKGSRCDIR.<replaceable>pkg</replaceable></varname> + is the location of the <replaceable>pkg</replaceable> + pkgsrc directory;</para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_DEPMETHOD.<replaceable>pkg</replaceable></varname> + (not shown above) controls whether we use + <varname>BUILD_DEPENDS</varname> or + <varname>DEPENDS</varname> to add the dependency on + <replaceable>pkg</replaceable>. + The build dependency is selected by setting + <varname>BUILDLINK_DEPMETHOD.<replaceable>pkg</replaceable></varname> + to <quote>build</quote>. By default, the + full dependency is used. + </para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_INCDIRS.<replaceable>pkg</replaceable></varname> + and + <varname>BUILDLINK_LIBDIRS.<replaceable>pkg</replaceable></varname> + (not shown above) are lists of subdirectories of + <filename>${BUILDLINK_PREFIX.<replaceable>pkg</replaceable>}</filename> + to add to the header and library search paths. These + default to <quote>include</quote> and <quote>lib</quote> + respectively. </para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_CPPFLAGS.<replaceable>pkg</replaceable></varname> + (not shown above) is the list of preprocessor flags to add + to <varname>CPPFLAGS</varname>, which are passed on to the + configure and build phases. The <quote>-I</quote> option + should be avoided and instead be handled using + <varname>BUILDLINK_INCDIRS.<replaceable>pkg</replaceable></varname> as + above.</para> + </listitem> + </itemizedlist> + + <para> The following variables are all optionally defined within + this second section (protected against multiple inclusion) and + control which package files are symlinked into + <filename>${BUILDLINK_DIR}</filename> and how their names are + transformed during the symlinking: </para> + + <itemizedlist> + <listitem> + <para> + <varname>BUILDLINK_FILES.<replaceable>pkg</replaceable></varname> + (not shown above) is a shell glob pattern relative to + <filename>${BUILDLINK_PREFIX.<replaceable>pkg</replaceable>}</filename> + to be symlinked into + <filename>${BUILDLINK_DIR}</filename>, + e.g. <filename>include/*.h</filename>. </para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_FILES_CMD.<replaceable>pkg</replaceable></varname> + (not shown above) is a shell pipeline that + outputs to stdout a list of files relative to + <filename>${BUILDLINK_PREFIX.<replaceable>pkg</replaceable>}</filename>. + The resulting files are to be symlinked + into <filename>${BUILDLINK_DIR}</filename>. By default, + this takes the <filename>+CONTENTS</filename> of a + <replaceable>pkg</replaceable> and filters it through + <varname>${BUILDLINK_CONTENTS_FILTER.<replaceable>pkg</replaceable>}</varname>. + </para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_CONTENTS_FILTER.<replaceable>pkg</replaceable></varname> + (not shown above) is a filter command that filters + <filename>+CONTENTS</filename> input into a list of files + relative to + <filename>${BUILDLINK_PREFIX.<replaceable>pkg</replaceable>}</filename> + on stdout. By default for overwrite packages, + <varname>BUILDLINK_CONTENTS_FILTER.<replaceable>pkg</replaceable></varname> + outputs the contents of the <filename>include</filename> + and <filename>lib</filename> directories in the package + <filename>+CONTENTS</filename>, and for pkgviews packages, + it outputs any libtool archives in + <filename>lib</filename> directories. + </para> + </listitem> + + <listitem> + <para> + <varname>BUILDLINK_TRANSFORM.<replaceable>pkg</replaceable></varname> + (not shown above) is a list of sed arguments used to + transform the name of the source filename into a + destination filename, e.g. <command>-e + "s|/curses.h|/ncurses.h|g"</command>. + </para> + </listitem> + </itemizedlist> + + <para> The last section includes any + <filename>buildlink3.mk</filename> needed for + <replaceable>pkg</replaceable>'s library dependencies. + Including these <filename>buildlink3.mk</filename> files + means that the headers and libraries for these + dependencies are also symlinked into + <filename>${BUILDLINK_DIR}</filename> + whenever the <replaceable>pkg</replaceable> + <filename>buildlink3.mk</filename> + file is included. + </para> + </sect2> + + <sect2> + <title>Updating <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> in <filename>buildlink3.mk</filename> files</title> + + <para> + There are two situations that require increasing the + dependency listed in + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> + after a package update: </para> + + <orderedlist> + <listitem> + <para> if the sonames (major number of the library version) + of any installed shared libraries change; </para> + </listitem> + + <listitem> + <para> if the API or interface to the header files change. </para> + </listitem> + </orderedlist> + + <para> In these cases, + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> + should be adjusted to require at least the new package + version. In some cases, the packages that depend on this new + version may need their <varname>PKGREVISION</varname>s + increased and, if they have <filename>buildlink3.mk</filename> + files, their + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> + adjusted, too. This is needed so that binary packages made + using it will require the correct package dependency and not + settle for an older one which will not contain the necessary + shared libraries. </para> + + <para> Please take careful consideration before adjusting + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname> + as we don't want to cause unneeded package deletions and + rebuilds. In many cases, new versions of packages work just + fine with older dependencies. See <xref + linkend="dependencies"/> and <xref linkend="buildlink"/> for + more information about dependencies on other packages, + including the <varname>BUILDLINK_RECOMMENDED</varname> and + <varname>RECOMMENDED</varname> definitions. </para> + </sect2> + </sect1> + + <sect1> + <title>Writing <filename>builtin.mk</filename> files</title> + + <para> + Some packages in pkgsrc install headers and libraries that + coincide with headers and libraries present in the base system. + Aside from a <filename>buildlink3.mk</filename> file, these + packages should also include a <filename>builtin.mk</filename> + file that includes the necessary checks to decide whether using + the built-in software or the pkgsrc software is + appropriate. </para> + + <para> The only requirements of a builtin.mk file for + <replaceable>pkg</replaceable> are: + </para> + + <orderedlist> + <listitem> + <para> It should set + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + to either <quote>yes</quote> or <quote>no</quote> + after it is included. + </para> + </listitem> + + <listitem> + <para> It should <emphasis>not</emphasis> override any + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + which is already set before the + <filename>builtin.mk</filename> file is included. + </para> + </listitem> + + <listitem> + <para> It should be written to allow multiple inclusion. This + is <emphasis>very</emphasis> important and takes careful + attention to <filename>Makefile</filename> coding. + </para> + </listitem> + </orderedlist> + + <sect2> + <title>Anatomy of a <filename>builtin.mk</filename> file</title> + + <para>The following is the recommended template for builtin.mk + files: </para> + + <programlisting> +.if !defined(IS_BUILTIN.foo) +# +# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo" +# genuinely exists in the system or not. +# +IS_BUILTIN.foo?= no + +# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package +# version can be determined. +# +. if !empty(IS_BUILTIN.foo:M[yY][eE][sS]) +BUILTIN_PKG.foo?= foo-1.0 +. endif +.endif # IS_BUILTIN.foo + +.if !defined(USE_BUILTIN.foo) +USE_BUILTIN.foo?= ${IS_BUILTIN.foo} +. if defined(BUILTIN_PKG.foo) +. for _depend_ in ${BUILDLINK_DEPENDS.foo} +. if !empty(USE_BUILTIN.foo:M[yY][eE][sS]) +USE_BUILTIN.foo!= \ + if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \ + ${ECHO} "yes"; \ + else \ + ${ECHO} "no"; \ + fi +. endif +. endfor +. endif +.endif # USE_BUILTIN.foo + +CHECK_BUILTIN.foo?= no +.if !empty(CHECK_BUILTIN.foo:M[nN][oO]) +# +# Here we place code that depends on whether USE_BUILTIN.foo is set to +# "yes" or "no". +# +.endif # CHECK_BUILTIN.foo + </programlisting> + + <para> The first section sets + <varname>IS_BUILTIN.<replaceable>pkg</replaceable></varname> + depending on if <replaceable>pkg</replaceable> really exists + in the base system. This should not be a base system software + with similar functionality to <replaceable>pkg</replaceable>; + it should only be <quote>yes</quote> if the actual package is + included as part of the base system. This variable is only + used internally within the <filename>builtin.mk</filename> + file. </para> + + <para> The second section sets + <varname>BUILTIN_PKG.<replaceable>pkg</replaceable></varname> + to the version of <replaceable>pkg</replaceable> in the base + system if it exists (if + <varname>IS_BUILTIN.<replaceable>pkg</replaceable></varname> + is <quote>yes</quote>). This variable is only used internally + within the <filename>builtin.mk</filename> file. </para> + + <para> The third section sets + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + and is <emphasis>required</emphasis> in all + <filename>builtin.mk</filename> files. The code in this + section must make the determination whether the built-in + software is adequate to satisfy the dependencies listed in + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname>. + This is typically done by comparing + <varname>BUILTIN_PKG.<replaceable>pkg</replaceable></varname> + against each of the dependencies in + <varname>BUILDLINK_DEPENDS.<replaceable>pkg</replaceable></varname>. + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + <emphasis>must</emphasis> be set to the correct value by the + end of the <filename>builtin.mk</filename> file. Note that + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + may be <quote>yes</quote> even if + <varname>IS_BUILTIN.<replaceable>pkg</replaceable></varname> + is <quote>no</quote> because we may make the determination + that the built-in version of the software is similar enough to + be used as a replacement. </para> + + <para> The last section is guarded by + <varname>CHECK_BUILTIN.<replaceable>pkg</replaceable></varname>, + and includes code that uses the value of + <varname>USE_BUILTIN.<replaceable>pkg</replaceable></varname> + set in the previous section. This typically includes, e.g., + adding additional dependency restrictions and listing + additional files to symlink into + <filename>${BUILDLINK_DIR}</filename> (via + <varname>BUILDLINK_FILES.<replaceable>pkg</replaceable></varname>). + </para> + </sect2> + + <sect2> + <title>Global preferences for native or pkgsrc software</title> + + <para> + When building packages, it's possible to choose whether to set + a global preference for using either the built-in (native) + version or the pkgsrc version of software to satisfy a + dependency. This is controlled by setting + <varname>PREFER_PKGSRC</varname> and + <varname>PREFER_NATIVE</varname>. These variables take values + of either <quote>yes</quote>, <quote>no</quote>, or a list of + packages. <varname>PREFER_PKGSRC</varname> tells pkgsrc to + use the pkgsrc versions of software, while + <varname>PREFER_NATIVE</varname> tells pkgsrc to use the + built-in versions. Preferences are determined by the most + specific instance of the package in either + <varname>PREFER_PKGSRC</varname> or + <varname>PREFER_NATIVE</varname>. If a package is specified + in neither or in both variables, then + <varname>PREFER_PKGSRC</varname> has precedence over + <varname>PREFER_NATIVE</varname>. For example, to require + using pkgsrc versions of software for all but the most basic + bits on a NetBSD system, you can set: </para> + + <programlisting> + PREFER_PKGSRC= yes + PREFER_NATIVE= getopt skey tcp_wrappers + </programlisting> + + <para> A package <emphasis>must</emphasis> have a + <filename>builtin.mk</filename> + file to be listed in <varname>PREFER_NATIVE</varname>, + otherwise it is simply ignored in that list. + </para> + </sect2> + </sect1> +</chapter> diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent new file mode 100644 index 00000000000..4c2ed10da9e --- /dev/null +++ b/doc/guide/files/chapters.ent @@ -0,0 +1,24 @@ +<!-- + Creates entities for each chapter in the pkgsrc book. + + $NetBSD: chapters.ent,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ +--> + +<!-- users-guide --> +<!ENTITY chap.intro SYSTEM "introduction.xml"> +<!ENTITY chap.getting SYSTEM "getting.xml"> +<!ENTITY chap.using SYSTEM "using.xml"> +<!ENTITY chap.binary SYSTEM "binary.xml"> +<!ENTITY chap.components SYSTEM "components.xml"> +<!ENTITY chap.plist SYSTEM "plist.xml"> +<!ENTITY chap.fixes SYSTEM "fixes.xml"> +<!ENTITY chap.build SYSTEM "build.xml"> +<!ENTITY chap.buildlink SYSTEM "buildlink.xml"> +<!ENTITY chap.options SYSTEM "options.xml"> +<!ENTITY chap.debug SYSTEM "debug.xml"> +<!ENTITY chap.faq SYSTEM "faq.xml"> +<!ENTITY chap.submit SYSTEM "submit.xml"> +<!ENTITY chap.examples SYSTEM "examples.xml"> +<!ENTITY chap.logs SYSTEM "logs.xml"> +<!ENTITY chap.ftp-layout SYSTEM "ftp-layout.xml"> +<!ENTITY chap.platform SYSTEM "platforms.xml"> diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml new file mode 100644 index 00000000000..f187209b2f6 --- /dev/null +++ b/doc/guide/files/components.xml @@ -0,0 +1,400 @@ +<!-- $NetBSD: components.xml,v 1.1.1.1 2004/10/21 14:27:38 grant Exp $ --> + +<chapter id="components"> <?dbhtml filename="components.html"?> + <title>Package components - files, directories and contents</title> + + <para> Whenever you're preparing a package, there are a number of + files involved which are described in the following + sections. </para> + + <sect1 id="components.Makefile"> + <title><filename>Makefile</filename></title> + + <para>Building, installation and creation of a binary package are all + controlled by the package's <filename>Makefile</filename>.</para> + + <para>There is a <filename>Makefile</filename> for each package. + This file includes the standard + <filename>bsd.pkg.mk</filename> file (referenced as + <filename>../../mk/bsd.pkg.mk</filename>), which sets all the + definitions and actions necessary for the package to compile and + install itself. The mandatory variables are the + <varname>DISTNAME</varname> which specifies the base name + of the distribution file to be downloaded from the site on the + Internet, <varname>MASTER_SITES</varname> which specifies that site, + <varname>CATEGORIES</varname> which denotes the + categories into which the package falls, <varname>PKGNAME</varname> + which is the name of the package, the <varname>MAINTAINER</varname>'s + name, and the <varname>COMMENT</varname> variable, which should + contain a one-line description of the package (the package name + should not appear, it will be added automatically). The maintainer + variable is there so that anyone who quibbles with the (always + completely correct) decisions taken by the guy who maintains the + package can complain vigorously, or send chocolate as a sign of + appreciation.</para> + + <para>The <varname>MASTER_SITES</varname> may be set to one of the + predefined sites:</para> + + <programlisting> + ${MASTER_SITE_APACHE} + ${MASTER_SITE_DEBIAN} + ${MASTER_SITE_GNOME} + ${MASTER_SITE_GNU} + ${MASTER_SITE_GNUSTEP} + ${MASTER_SITE_MOZILLA} + ${MASTER_SITE_PERL_CPAN} + ${MASTER_SITE_SOURCEFORGE} + ${MASTER_SITE_SUNSITE} + ${MASTER_SITE_R_CRAN} + ${MASTER_SITE_SUSE} + ${MASTER_SITE_TEX_CTAN} + ${MASTER_SITE_XCONTRIB} + ${MASTER_SITE_XEMACS} </programlisting> + + <para>If one of these predefined sites is chosen, you may require the + ability to specify a subdirectory of that site. Since these macros + may expand to more than one actual site, you + <emphasis>must</emphasis> use the following construct to specify a + subdirectory:</para> + + <programlisting> + ${MASTER_SITE_GNU:=subdirectory/name/} + ${MASTER_SITE_SOURCEFORGE:=project_name/} </programlisting> + + <para>Note the trailing slash after the subdirectory name.</para> + + <note> + <para><varname>MASTER_SITE_SUBDIR</varname> has been deprecated and + <emphasis>should no longer be used</emphasis>.</para> + </note> + + <para>If the package has multiple <varname>DISTFILES</varname> or multiple + <varname>PATCHFILES</varname> from different + sites, set <varname>SITES_foo</varname> to a list of URI's where file + <quote>foo</quote> may be found. <quote>foo</quote> + includes the suffix, e.g.</para> + +<programlisting>DISTFILES= ${DISTNAME}${EXTRACT_SUFX} +DISTFILES+= foo-file.tar.gz +SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \ + http://www.somewhereelse.com/mirror/somehow/</programlisting> + + <para>Note that the normal default setting of <varname>DISTFILES</varname> + must be made explicit if you want to add to it (rather than replace + it), as you usually would.</para> + + <para>Currently the following values are available for + <varname>CATEGORIES</varname>. If more than + one is used, they need to be separated by spaces:</para> + + <programlisting> +archivers cross geography meta-pkgs security +audio databases graphics misc shells +benchmarks devel ham multimedia sysutils +biology editors inputmethod net textproc +cad emulators lang news time +chat finance mail parallel wm +comms fonts math pkgtools www +converters games mbone print x11</programlisting> + + <para> Please pay attention to the following gotchas: </para> + + <itemizedlist> + <listitem> + <para>Add <varname>MANCOMPRESSED</varname> if manpages are installed in + compressed form by the package; see comment in + <filename>bsd.pkg.mk</filename>.</para> + </listitem> + + <listitem> + <para>Replace <filename>/usr/local</filename> with + <quote>${PREFIX}</quote> in all files (see patches, below).</para> + </listitem> + + <listitem> + <para>If the package installs any info files, see + <xref linkend="faq.info-files"/>.</para> + </listitem> + + <listitem> + <para>Set <varname>MAINTAINER</varname> to be yourself. + If you really can't maintain the package for future updates, + set it to <email>tech-pkg@NetBSD.org</email>.</para> + </listitem> + + <listitem> + <para>If a home page for the software in question exists, + add the variable <varname>HOMEPAGE</varname> right after + <varname>MAINTAINER</varname>. The value of this + variable should be the URL for the home page.</para> + </listitem> + + <listitem> + <para>Be sure to set the <varname>COMMENT</varname> variable to a short + description of the package, not containing the pkg's name.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="components.distinfo"> + <title><filename>distinfo</filename></title> + + <para>Most important, the mandatory message digest, or checksum, of all the + distfiles needed for the package to compile, confirming they match the + original file distributed by the author. This ensures that the + distfile retrieved from the Internet has not been corrupted during + transfer or altered by a malign force to introduce a security hole. + It is generated using the <command>make makesum</command> command. + The digest algorithm used was, at one stage, md5, but that was felt + lacking compared to sha1, and so sha1 is now the default algorithm. + The distfile size is also generated and stored in new distinfo files. + The <pkg>pkgtools/digest</pkg> utility calculates all of the digests + in the distinfo file, and it provides various different algorithms. + At the current time, the algorithms provided are: + <emphasis>md5</emphasis>, <emphasis>rmd160</emphasis>, + <emphasis>sha1</emphasis>, <emphasis>sha256</emphasis>, + <emphasis>sha384</emphasis> and <emphasis>sha512</emphasis>.</para> + + <para>Some packages have different sets of distfiles on a per architecture + basis, for example <pkg>www/navigator</pkg>). These are kept in the + same distinfo file and care should be taken when upgrading such a + package to ensure distfile information is not lost.</para> + + <para>The message digest/checksum for all the official patches found in the + <filename>patches/</filename> directory (see + <xref linkend="components.patches"/>) for the package is also stored in + the <filename>distinfo</filename> file. This is a message + digest/checksum of all lines in the patch file except the &os; RCS Id. + This file is generated by invoking <command>make + makepatchsum</command> (or <command>make mps</command> if you're + in a hurry).</para> + </sect1> + + <sect1 id="components.patches"> + <title>patches/*</title> + + <para>This directory contains files that are used by the + &man.patch.1; command to + modify the sources as distributed in the distribution file into a form + that will compile and run perfectly on &os;. The files are applied + successively in alphabetic order (as returned by a shell + <quote>patches/patch-*</quote> glob expansion), so + <filename>patch-aa</filename> is applied before + <filename>patch-ab</filename>, etc.</para> + + <para> Patch files which are optional and will depend on local + site configuration can be included with names matching the + pattern <filename>patches/patch-optional-*</filename>. Their + suffixes should match the configuration options. The selected + optional patch file names should be assigned to the variable + <varname>OPTIONAL_PATCHFILES</varname>. They will not be + applied by default. + </para> + + <para> For example if a package data file needs patching to + indicate the default local printer paper size as specified in + the <varname>$PAPERSIZE</varname> file you can include patches + for all the possible paper sizes other than the one the package + comes configured for by default. In this case you might have a + patch called + "<filename>patch-optional-Letter-papersize</filename>" and/or + another patch called + "<filename>patch-optional-A4-papersize</filename>". In your + <filename>Makefile</filename> you would select between them with + the following construct: + </para> + + <programlisting> + PATCHDIR= ${.CURDIR}/patches + .if exists(${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize) + OPTIONAL_PATCHFILES+= ${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize + .endif </programlisting> + + <para> Note that you have to define the value of + <varname>PATCHDIR</varname> in order to use it in a + <quote><command>.if</command></quote> statement like this as + otherwise it's not defined until too late during the processing + of the Makefile. You should use a + <quote><command>.if</command></quote> statement in order to + avoid problems should the configuration item + (<varname>$PAPERSIZE</varname> in this example) be set to an + unexpected value. + </para> + + <para>The <filename>patch-*</filename> files should be in + <command>diff -bu</command> format, and apply without a fuzz to avoid + problems. (To force patches to apply + with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>). + Furthermore, do not put changes for more than one file into a single + patch-file, as this will make future modifications more difficult.</para> + + <para>Similar, a file should be patched at most once, not several times by + several different patches. If a file needs several patches, they should + be combined into one file.</para> + + <para>One important thing to mention is to pay attention that no RCS IDs + get stored in the patch files, as these will cause problems when + later checked into the &os; CVS tree. Use the + <command>pkgdiff</command> from the + <pkg>pkgtools/pkgdiff</pkg> package to avoid these problems.</para> + + <para>For even more automation, we recommend using <command>mkpatches</command> from the same + package to make a whole set of patches. You just have to backup files + before you edit them to <filename>filename.orig</filename>, e.g. with + <command>cp -p filename filename.orig</command> or, easier, by using + <command>pkgvi</command> again from the same package. If you upgrade a package + this way, you can easily compare the new set of patches with the + previously existing one with <command>patchdiff</command>.</para> + + <para>When you have finished a package, remember to generate the checksums + for the patch files by using the <command>make makepatchsum</command> + command, see <xref linkend="components.distinfo"/>.</para> + + <para>Patch files that are distributed by the author or other + maintainers can be listed in + <varname>$PATCHFILES</varname>. </para> + + <para>If it is desired to store any patches that should not be committed into + pkgsrc, they can be kept outside the pkgsrc tree in the + <filename>$LOCALPATCHES</filename> + directory. The directory tree there is expected to have the same + <quote>category/package</quote> structure as pkgsrc, and patches are + expected to be stored inside these dirs (also known as + <filename>$LOCALPATCHES/$PKGPATH</filename>). For + example if you want to keep a private patch for + <filename>pkgsrc/graphics/png</filename>, keep + it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All + files in the named directory are expected to be patch files, and + <emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para> + </sect1> + + <sect1> + <title>Other mandatory files</title> + + <variablelist> + <varlistentry> + <term><filename>DESCR</filename></term> + + <listitem> + <para>A multi-line description of the piece of software. This should include + any credits where they are due. Please bear in mind that others do not + share your sense of humour (or spelling idiosyncrasies), and that others + will read everything that you write here.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>PLIST</filename></term> + + <listitem> + <para> + This file governs the files that are installed on your system: all the + binaries, manual pages, etc. There are other directives which may be + entered in this file, to control the creation and deletion of + directories, and the location of inserted files. + See <xref linkend="plist"/> for more information. </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="components.optional"> + <title>Optional files</title> + + <variablelist> + <varlistentry> + <term><filename>INSTALL</filename></term> + + <listitem> + <para>This shell script is invoked twice by &man.pkg.add.1;. + First time after package + extraction and before files are moved in place, the second time after + the files to install are moved in place. This can be used to do any + custom procedures not possible with @exec commands in + <filename>PLIST</filename>. See + &man.pkg.add.1; and &man.pkg.create.1; for more information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>DEINSTALL</filename></term> + + <listitem> + <para>This script is executed before and after any files are removed. It is + this script's responsibility to clean up any additional messy details + around the package's installation, since all pkg_delete knows is how to + delete the files created in the original distribution. + See &man.pkg.delete.1; + and &man.pkg.create.1; for more information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>MESSAGE</filename></term> + + <listitem> + <para>Display this file after installation of the package. + Useful for things like legal notices on almost-free + software and hints for updating config files after + installing modules for apache, PHP etc. + Please note that you can modify variables in it easily by using + <varname>MESSAGE_SUBST</varname> in the package's + <filename>Makefile</filename>:</para> + + <programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting> + + <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in + <filename>MESSAGE</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title><filename>work*</filename></title> + + <para>When you type <command>make</command> the distribution files are + unpacked into this directory. It can be removed by running + <command>make clean</command>. Besides the sources, this + directory is also used to keep various timestamp files.</para> + + <para> If a package doesn't create a subdirectory for itself (like + GNU software does, for instance), but extracts itself in the + current directory, you should set <varname>WRKSRC</varname> + accordingly, e.g. <pkg>editors/sam</pkg> again, but the quick + answer is: </para> + + <programlisting>WRKSRC= ${WRKDIR}</programlisting> + + <para> Please note that the old <varname>NO_WRKSUBDIR</varname> + has been deprecated and should not be used. Also, if your + package doesn't create a subdir with the name of + <varname>DISTNAME</varname> but some different name, set + <varname>WRKSRC</varname> to point to the proper name in + <filename>${WRKDIR}</filename>. See <pkg>lang/tcl</pkg> and + <pkg>x11/tk</pkg> for examples, and here is another one: </para> + + <programlisting>WRKSRC= ${WRKDIR}/${DISTNAME}/unix</programlisting> + + <para> The name of the working directory created by pkgsrc is + <filename>work</filename> by default. If the same pkgsrc tree + should be used on several different platforms, the variable + <varname>OBJMACHINE</varname> can be set in /etc/mk.conf to + attach the platform to the directory name, + e.g. <filename>work.i386</filename> or + <filename>work.sparc</filename>. </para> + </sect1> + + <sect1> + <title><filename>files/*</filename></title> + + <para>If you have any files that you wish to be placed in the package prior + to configuration or building, you could place these files here and use + a <quote>${CP}</quote> command in the + <quote>pre-configure</quote> target to achieve + this. Alternatively, you could simply diff the file against + <filename>/dev/null</filename> and use the patch mechanism to manage + the creation of this file.</para> + </sect1> +</chapter> diff --git a/doc/guide/files/debug.xml b/doc/guide/files/debug.xml new file mode 100644 index 00000000000..9181f2c6648 --- /dev/null +++ b/doc/guide/files/debug.xml @@ -0,0 +1,130 @@ +<!-- $NetBSD: debug.xml,v 1.1.1.1 2004/10/21 14:27:38 grant Exp $ --> + +<chapter id="debug"> + <title>Debugging</title> + + <para>To check out all the gotchas when building a package, here are the steps + that I do in order to get a package working. Please note this is basically + the same as what was explained in the previous sections, only with some + debugging aids.</para> + + <itemizedlist> + <listitem> + <para>Be sure to set <varname>PKG_DEVELOPER=1</varname> + in <filename>/etc/mk.conf</filename></para> + </listitem> + + <listitem> + <para>Install <pkg>pkgtools/url2pkg</pkg>, create a directory + for a new package, change into it, then run + <command>url2pkg</command>:</para> + + <screen>&cprompt; <userinput>mkdir /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput> +&cprompt; <userinput>cd /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput> +&cprompt; <userinput>url2pkg http://www.example.com/path/to/distfile.tar.gz</userinput></screen> + </listitem> + + <listitem> + <para>Edit the <filename>Makefile</filename> as requested.</para> + </listitem> + + <listitem> + <para>Fill in the <filename>DESCR</filename> file</para> + </listitem> + + <listitem> + <para>Run <command>make configure</command> + </para> + </listitem> + + <listitem> + <para>Add any dependencies glimpsed from documentation and the + configure step to the package's + <filename>Makefile</filename>.</para> + </listitem> + + <listitem> + <para>Make the package compile, doing multiple rounds of</para> + + <screen>&cprompt; <userinput>make</userinput> +&cprompt; <userinput>pkgvi ${WRKSRC}/some/file/that/does/not/compile</userinput> +&cprompt; <userinput>mkpatches</userinput> +&cprompt; <userinput>patchdiff</userinput> +&cprompt; <userinput>mv ${WRKDIR}/.newpatches/* patches</userinput> +&cprompt; <userinput>make mps</userinput> +&cprompt; <userinput>make clean</userinput></screen> + + <para>Doing as non-root user will ensure that no files are modified that + shouldn't be, especially during the build + phase. <command>mkpatches</command>, + <command>patchdiff</command> and <command>pkgvi</command> are + from the <pkg>pkgtools/pkgdiff</pkg> package. </para> + </listitem> + + <listitem> + <para>Look at the <filename>Makefile</filename>, fix if necessary; + see <xref linkend="components.Makefile"/>.</para> + </listitem> + + <listitem> + <para>Generate a <filename>PLIST</filename>:</para> + + <screen>&rprompt; <userinput>make install</userinput> +&rprompt; <userinput>make print-PLIST >PLIST</userinput> +&rprompt; <userinput>make deinstall</userinput> +&rprompt; <userinput>make install</userinput> +&rprompt; <userinput>make deinstall</userinput></screen> + + <para>You usually need to be <username>root</username> to do this. + Look if there are any files left:</para> + + <screen>&rprompt; <userinput>make print-PLIST</userinput></screen> + + <para>If this reveals any files that are missing in + <filename>PLIST</filename>, add them.</para> + </listitem> + + <listitem> + <para>Now that the <filename>PLIST</filename> is OK, + install the package again and make a binary package:</para> + + <screen>&rprompt; <userinput>make reinstall</userinput> +&rprompt; <userinput>make package</userinput></screen> + </listitem> + + <listitem> + <para>Delete the installed package:</para> + + <screen>&rprompt; <userinput>pkg_delete blub</userinput></screen> + </listitem> + + <listitem> + <para>Repeat the above <command>make print-PLIST</command> command, + which shouldn't find anything now:</para> + + <screen>&rprompt; <userinput>make print-PLIST</userinput></screen> + </listitem> + + <listitem> + <para>Reinstall the binary package:</para> + + <screen>&rprompt; <userinput>pkgadd .../blub.tgz</userinput></screen> + </listitem> + + <listitem> + <para>Play with it. Make sure everything works.</para> + </listitem> + + <listitem> + <para>Run <command>pkglint</command> from <pkg>pkgtools/pkglint</pkg>, + and fix the problems it reports:</para> + + <screen>&rprompt; <userinput>pkglint</userinput></screen> + </listitem> + + <listitem> + <para>Submit (or commit, if you have cvs access); + see <xref linkend="submit"/>.</para> + </listitem> + </itemizedlist> +</chapter> diff --git a/doc/guide/files/examples.xml b/doc/guide/files/examples.xml new file mode 100644 index 00000000000..935320b8399 --- /dev/null +++ b/doc/guide/files/examples.xml @@ -0,0 +1,202 @@ +<!-- $NetBSD: examples.xml,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ --> + +<appendix id="examples"> + <title>A simple example package: bison</title> + + <para>We checked to find a piece of software that wasn't in the packages + collection, and picked GNU bison. Quite why someone would want to have + <command>bison</command> when Berkeley <command>yacc</command> is already + present in the tree is beyond us, but it's useful for the purposes of + this exercise.</para> + + <sect1> + <title>files</title> + + <sect2> + <title>Makefile</title> + + <programlisting># $NetBSD$ +# + +DISTNAME= bison-1.25 +CATEGORIES= devel +MASTER_SITES= ${MASTER_SITE_GNU} + +MAINTAINER= thorpej@NetBSD.org +HOMEPAGE= http://www.gnu.org/software/bison/bison.html +COMMENT= GNU yacc clone + +GNU_CONFIGURE= yes +INFO_FILES= bison.info + +.include "../../mk/bsd.pkg.mk"</programlisting> + </sect2> + + <sect2> + <title>DESCR</title> + + <programlisting>GNU version of yacc. Can make re-entrant parsers, and numerous other +improvements. Why you would want this when Berkeley &man.yacc.1; is part +of the &os; source tree is beyond me.</programlisting> + </sect2> + + <sect2> + <title>PLIST</title> + + <programlisting>@comment $NetBSD$ +bin/bison +man/man1/bison.1.gz +info/bison.info +info/bison.info-1 +info/bison.info-2 +info/bison.info-3 +info/bison.info-4 +info/bison.info-5 +share/bison.simple +share/bison.hairy</programlisting> + </sect2> + + <sect2> + <title>Checking a package with <command>pkglint</command></title> + + <para>The NetBSD package system comes with <pkg>pkgtools/pkglint</pkg> + which helps to check the contents of these + files. After installation it is quite easy to use, just change to the + directory of the package you wish to examine and execute + <command>pkglint</command>:</para> + + <screen>&uprompt; <userinput>pkglint</userinput> +OK: checking ./DESCR. +OK: checking Makefile. +OK: checking distinfo. +OK: checking patches/patch-aa. +looks fine.</screen> + + <para>Depending on the supplied command line arguments (see pkglint(1)) + more verbose checks will be performed. Use e.g. + <command>pkglint -v</command> for a very verbose check.</para> + </sect2> + </sect1> + + <sect1> + <title>Steps for building, installing, packaging</title> + + <para>Create the directory where the package lives, + plus any auxiliary directories:</para> + + <screen>&rprompt; <userinput>cd /usr/pkgsrc/lang</userinput> +&rprompt; <userinput>mkdir bison</userinput> +&rprompt; <userinput>cd bison</userinput> +&rprompt; <userinput>mkdir patches</userinput></screen> + + <para>Create <filename>Makefile</filename>, <filename>DESCR</filename> and + <filename>PLIST</filename> (see <xref linkend="components"/>) + then continue with fetching the distfile:</para> + + <screen>&rprompt; <userinput>make fetch</userinput> +>> bison-1.25.tar.gz doesn't seem to exist on this system. +>> Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//. +Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/) +ftp: Error retrieving file: 500 Internal error + +>> Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//. +Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/) +ftp: Error retrieving file: 500 Internal error + +>> Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//. +Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/) +Successfully retrieved file.</screen> + + <para>Generate the checksum of the distfile into + <filename>distinfo</filename>:</para> + + <screen>&rprompt; <userinput>make makesum</userinput></screen> + + <para>Now compile:</para> + + <screen>&rprompt; <userinput>make</userinput> +>> Checksum OK for bison-1.25.tar.gz. +===> Extracting for bison-1.25 +===> Patching for bison-1.25 +===> Ignoring empty patch directory +===> Configuring for bison-1.25 +creating cache ./config.cache +checking for gcc... cc +checking whether we are using GNU C... yes +checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin +checking how to run the C preprocessor... cc -E +checking for minix/config.h... no +checking for POSIXized ISC... no +checking whether cross-compiling... no +checking for ANSI C header files... yes +checking for string.h... yes +checking for stdlib.h... yes +checking for memory.h... yes +checking for working const... yes +checking for working alloca.h... no +checking for alloca... yes +checking for strerror... yes +updating cache ./config.cache +creating ./config.status +creating Makefile +===> Building for bison-1.25 +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g LR0.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g allocate.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g closure.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g conflicts.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g derives.c +cc -c -DXPFILE=\"/usr/pkg/share/bison.simple\" -DXPFILE1=\"/usr/pkg/share/bison.hairy\" -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -g ./files.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getargs.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g gram.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g lalr.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g lex.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g main.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g nullable.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g output.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g print.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g reader.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g reduce.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g symtab.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g warshall.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g version.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getopt.c +cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include -g getopt1.c +cc -g -o bison LR0.o allocate.o closure.o conflicts.o derives.o files.o getargs.o gram.o lalr.o lex.o main.o nullable.o output.o print.o reader.o reduce.o symtab.o warshall.o version.o getopt.o getopt1.o +./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp() +rm -f bison.s1 +sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" < ./bison.simple > bison.s1</screen> + + <para>Everything seems OK, so install the files:</para> + + <screen>&rprompt; <userinput>make install</userinput> +>> Checksum OK for bison-1.25.tar.gz. +===> Installing for bison-1.25 +sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share /usr/pkg/info /usr/pkg/man/man1 +rm -f /usr/pkg/bin/bison +cd /usr/pkg/share; rm -f bison.simple bison.hairy +rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info* +install -c -o bin -g bin -m 555 bison /usr/pkg/bin/bison +/usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple +/usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy +cd .; for f in bison.info*; do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done +/usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1 +===> Registering installation for bison-1.25</screen> + + <para>You can now use bison, and also - if you decide so - remove it with + <command>pkg_delete bison</command>. Should you decide that you want a + binary package, do this now:</para> + + <screen>&rprompt; <userinput>make package</userinput> +>> Checksum OK for bison-1.25.tar.gz. +===> Building package for bison-1.25 +Creating package bison-1.25.tgz +Registering depends:. +Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'</screen> + + <para>Now that you don't need the source and object files + any more, clean up:</para> + + <screen>&rprompt; <userinput>make clean</userinput> +===> Cleaning for bison-1.25</screen> + </sect1> +</appendix> diff --git a/doc/guide/files/faq.xml b/doc/guide/files/faq.xml new file mode 100644 index 00000000000..39d8375c094 --- /dev/null +++ b/doc/guide/files/faq.xml @@ -0,0 +1,537 @@ +<!-- $NetBSD: faq.xml,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ --> + +<chapter id="faq"> <?dbhtml filename="faq.html"?> + <title>Frequently Asked Questions</title> + + <para> This section contains hints, tips & tricks on special + things in pkgsrc that we didn't find a better place for in the + previous chapters, and it contains items for both pkgsrc users and + developers. </para> + + <sect1> + <title>Is there a mailing list for pkg-related discussion?</title> + + <para> Yes, <email>tech-pkg@NetBSD.org</email> is the list for + discussing package related issues. To subscribe do: </para> + + <programlisting>&cprompt; echo subscribe tech-pkg | mail majordomo@NetBSD.org</programlisting> + + <para> An archive of the list is available at + <ulink url="http://mail-index.NetBSD.org/tech-pkg/">http://mail-index.NetBSD.org/tech-pkg/</ulink>. </para> +</sect1> + + +<sect1> + <title>Where's the pkgviews documentation?</title> + + <para> Pkgviews is tightly integrated with buildlink. You can find a + pkgviews User's guide in + <filename>pkgsrc/mk/buildlink3/PKGVIEWS_UG</filename>. + </para> +</sect1> + + +<sect1> + <title>Utilities for package management (pkgtools)</title> + + <para> + The <filename>pkgsrc/pkgtools</filename> directory pkgtools + contains a number of useful utilities for both users and + developers of pkgsrc. This section attempts only to make the + reader aware of the utilities and when they might be useful, and + not to duplicate the documentation that comes with each package. + </para> + + <para> + Utilities used by pkgsrc (automatically installed when needed): + </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/x11-links</pkg>: symlinks for use by + buildlink </para> + </listitem> + </itemizedlist> + + <para> OS tool augmentation (automatically installed when needed): + </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/digest</pkg>: + calculates SHA1 checksums (and other kinds) + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/libnbcompat</pkg>: + compat library for pkg tools + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/mtree</pkg>: + installed on non-BSD systems due to lack of native mtree + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkg_install</pkg>: + up-to-date replacement for /usr/sbin/pkg_install, or for + use on operating systems where pkg_install is not present + </para> + </listitem> + </itemizedlist> + + <para> Utilities used by pkgsrc (not automatically installed): + </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/pkg_tarup</pkg>: + create a binary package from an already-installed package. + used by 'make replace' to save the old package + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/xpkgwedge</pkg>: + put X11 packages someplace else (enabled by default) + </para> + </listitem> + </itemizedlist> + + <para> Utilities for keeping track of installed packages, being up + to date, etc: </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/pkg_chk</pkg>: + installs pkg_chk, which reports on packages whose installed + versions do not match the latest pkgsrc entries + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkgdep</pkg>: + makes dependency graphs of packages, to aid in choosing a + strategy for updating + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkgdepgraph</pkg>: + make graph from above (uses graphviz) + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkglint</pkg>: + This provides two distinct abilities: + check a pkgsrc entry for correctness (pkglint) + check for and remove out-of-date distfiles and binary + packages (lintpkgsrc) + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkgsurvey</pkg>: + report what packages you have installed + </para> + </listitem> + </itemizedlist> + + <para> Utilities for people maintaining or creating individual + packages: </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/pkgdiff</pkg>: + automate making and maintaining patches for a package (includes + pkgdiff, pkgvi, mkpatches, ...) + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/rpm2pkg</pkg>, <pkg>pkgtools/url2pkg</pkg>: + aids in converting to pkgsrc + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/gensolpkg</pkg>: + convert pkgsrc to a Solaris package + </para> + </listitem> + </itemizedlist> + + <para> Utilities for people maintaining pkgsrc (or more obscure + pkg utilities) </para> + + <itemizedlist> + <listitem> + <para> <pkg>pkgtools/pkgconflict</pkg>: + find packages that conflict but aren't marked as such + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/pkg_comp</pkg>: + build packages in a chrooted area + </para> + </listitem> + <listitem> + <para> <pkg>pkgtools/libkver</pkg>: + spoof kernel version for chrooted cross builds + </para> + </listitem> + </itemizedlist> +</sect1> + + +<sect1> + <title>How to use pkgsrc as non-root</title> + + <para> If you want to use pkgsrc as non-root user, you can set + some variables to make pkgsrc work under these + conditions. Please see <ulink + url="http://mail-index.NetBSD.org/tech-pkg/2003/09/27/0023.html">this + message</ulink> for more details. </para> +</sect1> + + +<sect1> + <title>How can I install/use XFree86 from pkgsrc?</title> + + <para> If you want to use XFree86 from pkgsrc instead of your + system's own X11 (<filename>/usr/X11R6</filename>, + <filename>/usr/openwin</filename>, ...), you will have to + add the following lines into <filename>mk.conf</filename>: + </para> + + <programlisting> + X11_TYPE=XFree86 + </programlisting> +</sect1> + + +<sect1> + <title>How can I install/use X.org from pkgsrc?</title> + + <para> If you want to use X.org from pkgsrc instead of your system's + own X11 (<filename>/usr/X11R6</filename>, + <filename>/usr/openwin</filename>, ...) you will have to add the + following lines into <filename>mk.conf</filename>: </para> + + <programlisting> + X11_TYPE=xorg + </programlisting> +</sect1> + + +<sect1> + <title>How to fetch files from behind a firewall</title> + + <para> If you are sitting behind a firewall which does not allow + direct connections to Internet hosts (i.e. non-NAT), you may + specify the relevant proxy hosts. This is done using an + environment variable in the form of a URL e.g. in Amdahl, the + machine <quote>orpheus.amdahl.com</quote> is one of the + firewalls, and it uses port 80 as the proxy port number. So the + proxy environment variables are: </para> + + <programlisting> ftp_proxy=ftp://orpheus.amdahl.com:80/ +http_proxy=http://orpheus.amdahl.com:80/</programlisting> +</sect1> + + +<sect1> + <title>How do I tell <command>make fetch</command> to do passive FTP?</title> + + <para> This depends on which utility is used to retrieve distfiles. From <filename>bsd.pkg.mk</filename>, <varname>FETCH_CMD</varname> is assigned the first available command from the following list: </para> + + <programlisting>${LOCALBASE}/bin/ftp +/usr/bin/ftp</programlisting> + + <para> On a default NetBSD installation, this will be + <filename>/usr/bin/ftp</filename>, which automatically tries + passive connections first, and falls back to active connections + if the server refuses to do passive. For the other tools, add + the following to your <filename>/etc/mk.conf</filename> file: + <varname>PASSIVE_FETCH=1</varname>. </para> + + <para> Having that option present will prevent + <filename>/usr/bin/ftp</filename> from falling back to active + transfers. </para> +</sect1> + + +<sect1> + <title>How to fetch all distfiles at once</title> + + <para> You would like to download all the distfiles in a single + batch from work or university, where you can't run a + <command>make fetch</command>. There is an archive of distfiles + on <ulink + url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/">ftp.NetBSD.org</ulink>, + but downloading the entire directory may not be appropriate. + </para> + + <para> The answer here is to do a <command>make + fetch-list</command> in <filename>/usr/pkgsrc</filename> or one + of it's subdirectories, carry the resulting list to your machine + at work/school and use it there If you don't have a + NetBSD-compatible ftp(1) (like lukemftp) at work, don't forget + to set <varname>FETCH_CMD</varname> to something that fetches a + URL: </para> + + <para> At home: </para> + + <screen><prompt>%</prompt> <userinput>cd /usr/pkgsrc</userinput> +<prompt>%</prompt> <userinput>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh</userinput> +<prompt>%</prompt> <userinput>scp /tmp/fetch.sh work:/tmp</userinput></screen> + + <para> At work: </para> + + <screen><prompt>%</prompt> <userinput>sh /tmp/fetch.sh</userinput></screen> + + <para> then tar up <filename>/tmp/distfiles</filename> and take it + home. </para> + + <para> If you have a machine running NetBSD, and you want to get + <emphasis>all</emphasis> distfiles (even ones that aren't for + your machine architecture), you can do so by using the + above-mentioned <command>make fetch-list</command> approach, or + fetch the distfiles directly by running: </para> + + <screen><prompt>%</prompt> <userinput>make mirror-distfiles</userinput></screen> + + <para> If you even decide to ignore + <varname>NO_{SRC,BIN}_ON_{FTP,CDROM}</varname>, then you can get + everything by running: </para> + + <screen><prompt>%</prompt> <userinput>make fetch NO_SKIP=yes</userinput></screen> +</sect1> + + +<sect1> + <title>What does <quote>Don't know how to make /usr/share/tmac/tmac.andoc</quote> mean?</title> + + <para> When compiling the <pkg>pkgtools/pkg_install</pkg> package, + you get the error from make that it doesn't know how to make + <filename>/usr/share/tmac/tmac.andoc</filename>? This indicates + that you don't have installed the <quote>text</quote> set on + your machine (nroff, ...). It is recommended to do that to + format manpages. </para> + + <para> In the case of the <pkg>pkgtools/pkg_install</pkg> package, + you can get away with setting <varname>NOMAN=YES</varname> + either in the environment or in + <filename>/etc/mk.conf</filename>. </para> +</sect1> + + +<sect1> + <title>What does <quote>Could not find bsd.own.mk</quote> mean?</title> + + <para> You didn't install the compiler set, + <filename>comp.tgz</filename>, when you installed your NetBSD + machine. Please get it and install it, by extracting it in + <filename>/</filename>: </para> + + <screen><prompt>#</prompt> <userinput>cd /</userinput> +<prompt>#</prompt> <userinput>tar --unlink -zxvpf .../comp.tgz</userinput></screen> + + <para> <filename>comp.tgz</filename> is part of every NetBSD + release. Get the one that corresponds to your release (determine + via <command>uname -r</command>). </para> +</sect1> + + +<sect1> + <title>Using 'sudo' with pkgsrc</title> + + <para> + When installing packages as non-root user and using the + just-in-time su(1) feature of pkgsrc, it can become annoying to + type in the root password for each required package + installed. To avoid this, the sudo package can be used, which + does password caching over a limited time. To use it, install + sudo (either as binary package or from <pkg>security/sudo</pkg>) + and then put the following into your + <filename>/etc/mk.conf</filename>: </para> + + <programlisting> + .if exists(/usr/pkg/bin/sudo) + SU_CMD=/usr/pkg/bin/sudo /bin/sh -c + .endif + </programlisting> +</sect1> + + +<sect1 id="faq.conf"> + <title>Configuration files handling and placement</title> + + <para> The global variable <varname>PKG_SYSCONFBASE</varname> + (and some others) can be set by the system administrator in + <filename>/etc/mk.conf</filename> to define the place where + configuration files get installed. Therefore, packages must be + adapted to support this feature. Keep in mind that you should + only install files that are strictly necessary in the + configuration directory, files that can go to + <filename>$PREFIX/share</filename> should go there. </para> + + <para> We will take a look at available variables first + (<filename>bsd.pkg.mk</filename> contains more + information). <varname>PKG_SYSCONFDIR</varname> is where the + configuration files for a package may be found (that is, the + full path, e.g. <filename>/etc</filename> or + <filename>/usr/pkg/etc</filename>). This value may be customized + in various ways: </para> + + <orderedlist> + <listitem> + <para> <varname>PKG_SYSCONFBASE</varname> is the main config + directory under which all package configuration files are to + be found. Users will typically want to set it to + <filename>/etc</filename>, or accept the default location of + <filename>$PREFIX/etc</filename>. </para> + </listitem> + + <listitem> + <para> <varname>PKG_SYSCONFSUBDIR</varname> is the + subdirectory of <varname>PKG_SYSCONFBASE</varname> under + which the configuration files for a particular package may + be found. Defaults to <varname>${SYSCONFBASE}</varname>. + </para> + </listitem> + + <listitem> + <para> <varname>PKG_SYSCONFVAR</varname> is the special + suffix used to distinguish any overriding values for a + particular package (see next item). It defaults to + <varname>${PKGBASE}</varname>, but for a collection of + related packages that should all have the same + <varname>PKG_SYSCONFDIR</varname> value, it can be set in + each of the package Makefiles to a common value. + </para> + </listitem> + + <listitem> + <para> + <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> + overrides the value of + <varname>${PKG_SYSCONFDIR}</varname> for packages with the + same value for <varname>PKG_SYSCONFVAR</varname>. + </para> + + <para> As an example, all the various KDE packages may want to + set <varname>PKG_SYSCONFVAR</varname> to <quote>kde</quote> + so admins can set <varname>PKG_SYSCONFDIR.kde</varname> in + <filename>/etc/mk.conf</filename> to define where to install + KDE config files. </para> + </listitem> + </orderedlist> + + <para> Programs' configuration directory should be defined during + the configure stage. Packages that use GNU autoconf can + usually do this by using the <quote>--sysconfdir</quote> + parameter, but this brings some problems as we will see now. + When you change this pathname in packages, you should not + allow them to install files in that directory + directly. Instead they need to install those files under + <filename>share/examples/${PKGNAME}</filename> so + <filename>PLIST</filename> can register them. </para> + + <para> Once you have the required configuration files in place + (under the <filename>share/examples</filename> directory) the + variable <varname>CONF_FILES</varname> should be set to copy + them into <varname>PKG_SYSCONFDIR</varname>. The contents of + this variable is formed by pairs of filenames; the first element + of the pair specifies the file inside the examples directory + (registered by <filename>PLIST</filename>) and the second + element specifies the target file. This is done this way to + allow binary packages to place files in the right directory + using + <filename>INSTALL</filename>/<filename>DEINSTALL</filename> + scripts which are created automatically. The package + <filename>Makefile</filename> must also set + <varname>USE_PKGINSTALL=YES</varname> to use these automatically + generated scripts. The automatic copying of config files can be + toggled by setting the environment variable + <varname>PKG_CONFIG</varname> prior to package installation. + </para> + + <para> Here is an example, taken from mail/mutt/Makefile: </para> + + <programlisting> EGDIR= ${PREFIX}/share/doc/mutt/samples +CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc</programlisting> + + <para> As you can see, this package installs configuration files + inside <varname>EGDIR</varname>, which are registered by + <filename>PLIST</filename>. After that, the variable + <varname>CONF_FILES</varname> lists the installed file first + and then the target file. Users will also get an automatic + message when files are installed using this method. </para> +</sect1> + + +<sect1 id="audit-packages"> + <title>Automated security checks</title> + + <para> Please be aware that there can often be bugs in third-party + software, and some of these bugs can leave a machine vulnerable + to exploitation by attackers. In an effort to lessen the + exposure, the NetBSD packages team maintains a database of + known-exploits to packages which have at one time been included + in pkgsrc. The database can be downloaded automatically, and a + security audit of all packages installed on a system can take + place. To do this, install the + <pkg>security/audit-packages</pkg> package. It has two + components: </para> + + <orderedlist> + <listitem> + <para> <quote>download-vulnerability-list</quote>, an easy way + to download a list of the security vulnerabilities + information. This list is kept up to date by the NetBSD + security officer and the NetBSD packages team, and is + distributed from the NetBSD ftp server: </para> + + <para> <ulink + url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities"/> + </para> + </listitem> + + <listitem> + <para> <quote>audit-packages</quote>, an easy way to audit the + current machine, checking each vulnerability which is + known. If a vulnerable package is installed, it will + be shown by output to stdout, including a description + of the type of vulnerability, and a URL containing more + information. </para> + </listitem> + </orderedlist> + + <para> Use of the audit-packages package is strongly recommended! + </para> + + <para> The following message is displayed as part of the + audit-packages installation procedure: </para> + + <screen> +=========================================================================== +$NetBSD: faq.xml,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ + +You may wish to have the vulnerabilities file downloaded daily so that +it remains current. This may be done by adding an appropriate entry +to the root users crontab(5) entry. For example the entry + +# download vulnerabilities file +0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1 + +will update the vulnerability list every day at 3AM. You may wish to do +this more often than once a day. + +In addition, you may wish to run the package audit from the daily +security script. This may be accomplished by adding the following +lines to /etc/security.local + +if [ -x ${PREFIX}/sbin/audit-packages ]; then + ${PREFIX}/sbin/audit-packages +fi + +=========================================================================== + </screen> + </sect1> + +</chapter> diff --git a/doc/guide/files/features.xml b/doc/guide/files/features.xml new file mode 100644 index 00000000000..40e37fbcc9d --- /dev/null +++ b/doc/guide/files/features.xml @@ -0,0 +1,1246 @@ +<!-- $NetBSD: features.xml,v 1.1.1.1 2004/10/21 14:27:38 grant Exp $ --> + +<chapter id="features"> <?dbhtml filename="features.html"?> +<title>FAQs & features of the package system</title> + +<sect1> +<title>Packages using GNU autoconf</title> + +<para> +If your package uses GNU autoconf created configure scripts, add the following +to your package's <filename>Makefile</filename>: +</para> + +<programlisting>GNU_CONFIGURE= yes</programlisting> + +<para> +Note that this appends <quote>--prefix=${PREFIX}</quote> to +<varname>CONFIGURE_ARGS</varname>, so you don't +have to do that yourself, but may not be desired. +</para> +</sect1> + + +<sect1> +<title>Other distrib methods than .tar.gz</title> + +<para> +If your package uses a different distribution method from +<filename>.tar.gz</filename>, take a +look at the package for <pkg>editors/sam</pkg>, which uses a gzipped shell archive +(shar), but the quick solution is to set +<varname>EXTRACT_SUFX</varname> to the name after the +<varname>DISTNAME</varname> field, and add the following to your +package's <filename>Makefile</filename>: +</para> + +<programlisting>EXTRACT_SUFX= .msg.gz +EXTRACT_CMD= zcat +EXTRACT_BEFORE_ARGS= +EXTRACT_AFTER_ARGS= |sh</programlisting> +</sect1> + + +<sect1> +<title>Packages not creating their own subdirectory</title> + +<para> +Your package doesn't create a subdirectory for itself (like GNU software +does, for instance), but extracts itself in the current directory: see +<pkg>editors/sam</pkg> again, but the quick answer is: +</para> + +<programlisting>WRKSRC= ${WRKDIR}</programlisting> + +<para> +Please note that the old: +</para> + +<programlisting>NO_WRKSUBDIR= yes</programlisting> + +<para> +has been deprecated and should not be used. +</para> +</sect1> + +<sect1> +<title>Custom configuration process</title> + +<para> +Your package uses a weird Configure script, eg. +<pkg>sysutils/top</pkg>. The quick answer is: +</para> + +<programlisting>HAS_CONFIGURE= yes +CONFIGURE_SCRIPT= Configure +CONFIGURE_ARGS+= netbsd13</programlisting> +</sect1> + + +<sect1> +<title>Packages not building in their DISTNAME directory</title> + +<para> +Your package builds in a different directory from its base +<varname>DISTNAME</varname> (see <pkg>lang/tcl</pkg> and +<pkg>x11/tk</pkg>). +</para> + +<programlisting>WRKSRC= ${WRKDIR}/${DISTNAME}/unix</programlisting> +</sect1> + + +<sect1> +<title>How to fetch all distfiles at once</title> + +<para> +You would like to download all the distfiles in a single batch from work or +university, where you can't run a <command>make fetch</command>. There +is an archive of distfiles on <ulink +url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/">ftp.NetBSD.org</ulink>, +but downloading the entire directory may not be appropriate. +</para> + +<para> +The answer here is to do a <command>make fetch-list</command> in +<filename>/usr/pkgsrc</filename>, carry the +resulting list to your machine at work/school and use it there If you don't +have a NetBSD-compatible ftp(1) (like lukemftp) at work, don't forget to +set <varname>FETCH_CMD</varname> to something that fetches a URL: +</para> + +<para> +At home: +</para> + +<screen><prompt>%</prompt> <userinput>cd /usr/pkgsrc</userinput> +<prompt>%</prompt> <userinput>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh</userinput> +<prompt>%</prompt> <userinput>scp /tmp/fetch.sh work:/tmp</userinput></screen> + +<para> +At work: +</para> + +<screen><prompt>%</prompt> <userinput>sh /tmp/fetch.sh</userinput></screen> + +<para> +then tar up <filename>/tmp/distfiles</filename> and take it home. +</para> + +<para> +If you have a machine running NetBSD, and you want to get +<emphasis>all</emphasis> distfiles +(even ones that aren't for your machine architecture), you can do so by +using the above-mentioned <command>make fetch-list</command> approach, or +fetch the distfiles directly by running: +</para> + +<screen><prompt>%</prompt> <userinput>make mirror-distfiles</userinput></screen> + +<para> +If you even decide to ignore <varname>NO_{SRC,BIN}_ON_{FTP,CDROM}</varname>, +then you can get everything by running: +</para> + +<screen><prompt>%</prompt> <userinput>make fetch NO_SKIP=yes</userinput></screen> +</sect1> + + +<sect1> +<title>How to fetch files from behind a firewall</title> + +<para> +If you are sitting behind a firewall which does not allow direct connections +to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts. +This is done using an environment variable in the form of a URL +e.g. in Amdahl, the machine <quote>orpheus.amdahl.com</quote> is one of +the firewalls, and it uses port 80 as the proxy port number. So the proxy +environment variables are: +</para> + +<programlisting>ftp_proxy=ftp://orpheus.amdahl.com:80/ +http_proxy=http://orpheus.amdahl.com:80/</programlisting> +</sect1> + + +<sect1> +<title>If your patch contains an RCS ID</title> + +<para> +See <xref linkend="components.patches"/> for information on how to +remove RCS IDs from patch files. +</para> +</sect1> + + +<sect1> +<title>How to pull in variables from /etc/mk.conf</title> + +<para> +The problem with package-defined variables that can be overridden via +<varname>MAKECONF</varname> or <filename>/etc/mk.conf</filename> is that make(1) expands a variable as it is +used, but evaluates preprocessor like statements (.if, .ifdef and +.ifndef) as they are read. So, to use any variable (which may be set +in <filename>/etc/mk.conf</filename>) in one of the .if* statements, the file +<filename>/etc/mk.conf</filename> +must be included before that .if* statement. +</para> + +<para> +Rather than have a number of ad-hoc ways of including +<filename>/etc/mk.conf</filename>, +should it exist, or <varname>MAKECONF</varname>, should it exist, include the +<filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package Makefile before any +preprocessor-like .if, .ifdef, or .ifndef statements: +</para> + +<programlisting>.include "../../mk/bsd.prefs.mk" + +.if defined(USE_MENUS) + ... +.endif</programlisting> + +<para> +If you wish to set the CFLAGS variable in /etc/mk.conf please make sure +to use: + +<screen>CFLAGS+= -your -flags</screen> + +Using <varname>CFLAGS=</varname> (ie without the <quote>+</quote>) may +lead to problems with packages that need to add their own flags. Also, +you may want to take a look at the <pkg>devel/cpuflags</pkg> package if +you're interested in optimization for the current CPU. +</para> +</sect1> + +<sect1> +<title>Is there a mailing list for pkg-related discussion?</title> + +<para> +Yes, <email>tech-pkg@NetBSD.org</email> is the list for discussing package +related issues. To subscribe do: +</para> + +<programlisting>% echo subscribe tech-pkg | mail majordomo@NetBSD.org</programlisting> +</sect1> + + +<sect1> +<title>How do I tell <command>make fetch</command> to do passive FTP?</title> + +<para> +This depends on which utility is used to retrieve distfiles. From +<filename>bsd.pkg.mk</filename>, <varname>FETCH_CMD</varname> is assigned +the first available command from the following list: +</para> + +<programlisting>/usr/bin/fetch +${LOCALBASE}/bsd/bin/ftp +/usr/bin/ftp</programlisting> + +<para> +On a default NetBSD install, this will be +<filename>/usr/bin/ftp</filename>, which automatically +tries passive connections first, and falls back to active connections if the +server refuses to do passive. For the other tools, add the following to your +<filename>/etc/mk.conf</filename> file: +<varname>PASSIVE_FETCH=1</varname>. +</para> + +<para> +Having that option present will prevent +<filename>/usr/bin/ftp</filename> from falling back to +active transfers. +</para> +</sect1> + + +<sect1> +<title>Dependencies on other packages</title> + +<para> +Your package may depend on some other package being present - and there are +various ways of expressing this dependency. NetBSD supports the +<varname>BUILD_DEPENDS</varname> and <varname>DEPENDS</varname> definitions, +as well as dependencies via +<filename>buildlink3.mk</filename> (see <!-- <xref +linkend="buildlink3"/> -->). +</para> + +<para> +The basic difference between the two definitions is as follows: The +<varname>DEPENDS</varname> definition registers that pre-requisite in the binary package, +whilst the <varname>BUILD_DEPENDS</varname> definition does not. +</para> + +<para> +This means that if you only need a package present whilst you are building, +it should be noted as a <varname>BUILD_DEPENDS</varname>. +</para> + +<para> +The format for a <varname>BUILD_DEPENDS</varname> and a +<varname>DEPENDS</varname> definition is: +</para> + +<programlisting><pre-req-package-name>:../../<category>/<pre-req-package></programlisting> + +<para> +Please note that the <quote>pre-req-package-name</quote> may include any of the wildcard +version numbers recognised by pkg_info(1). +</para> + +<orderedlist> + +<listitem> +<para> +If your package needs to use another package to build itself, this +is specified using the <varname>BUILD_DEPENDS</varname> definition. +</para> + +<programlisting>BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf</programlisting> +</listitem> + +<listitem> +<para> +If your package needs a library with which to link, this is specified +using the <varname>DEPENDS</varname> definition. An example of this is +the <pkg>print/lyx</pkg> +package, which uses the xpm library, version 3.4j to build. +</para> + +<programlisting>DEPENDS+= xpm-3.4j:../../graphics/xpm</programlisting> + +<para> +You can also use wildcards in package dependences: +</para> + +<programlisting>DEPENDS+= xpm-[0-9]*:../../graphics/xpm</programlisting> + +<para> +Note that such wildcard dependencies are retained when creating binary +packages. The dependency is checked when installing the binary +package and any package which matches the pattern will be used. +Wildcard dependencies should be used with care. +</para> + +<para> +The -[0-9]* should be used instead of -* to avoid potentially +ambiguous matches such as tk-postgresql matching a tk-* +<varname>DEPENDS</varname>. +</para> +</listitem> + +<listitem> +<para> +If your package needs some executable to be able to run correctly, this +is specified using the <varname>DEPENDS</varname> definition. The +<pkg>print/lyx</pkg> package needs +to be able to execute the latex binary from the teTeX package when it runs, +and that is specified: +</para> + +<programlisting>DEPENDS+= teTeX-[0-9]*:../../print/teTeX</programlisting> + +<para> +The comment about wildcard dependencies from previous paragraph +applies here, too. +</para> +</listitem> + +</orderedlist> + +<para> +If your package needs files from another package to build, see the +first part of the <quote>do-configure</quote> target +<pkg>print/ghostscript5</pkg> package +(it relies on the jpeg sources being present in source form during the +build): +</para> + +<programlisting>if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \ + cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} extract; \ +fi</programlisting> + +<para> +If you build any other packages that way, please make sure the working +files are deleted too when this package's working files are cleaned up. +The easiest way to do so is by adding a pre-clean target: +</para> + +<programlisting>pre-clean: + cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} clean</programlisting> + +<para> +Please also note the <varname>BUILD_USES_MSGFMT</varname> and +<varname>BUILD_USES_GETTEXT_M4</varname> definitions, +which are provided as convenience definitions. The former works out whether +msgfmt(1) is part of the base system, and, if it isn't, installs the +<pkg>devel/gettext</pkg> package. The latter adds a build dependency on either an +installed version of an older gettext package, or if it isn't, installs the +<pkg>devel/gettext-m4</pkg> package. +</para> +</sect1> + + +<sect1> +<title>Conflicts with other packages</title> + +<para> +Your package may conflict with other packages a user might already have +installed on his system, e.g. if your package installs the same set of +files like another package in our pkgsrc tree. +</para> + +<para> +In this case you can set <varname>CONFLICTS</varname> to a space separated +list of packages (including version string) your package conflicts with. +</para> + +<para> +For example <pkg>x11/Xaw3d</pkg> and +<pkg>x11/Xaw-Xpm</pkg> install provide the +same shared library, thus you set in +<filename>pkgsrc/x11/Xaw3d/Makefile</filename>: +</para> + +<programlisting>CONFLICTS= Xaw-Xpm-[0-9]*</programlisting> + +<para> +and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>: +</para> + +<programlisting>CONFLICTS= Xaw3d-[0-9]*</programlisting> + +<para> +Packages will automatically conflict with other packages with the name prefix +and a different version string. <quote>Xaw3d-1.5</quote> e.g. will automatically conflict +with the older version <quote>Xaw3d-1.3</quote>. +</para> +</sect1> + + +<sect1> +<title>Software which has a WWW Home Page</title> + +<para> +The NetBSD packages system now supports a variable called +<varname>HOMEPAGE</varname>. +If the software being packaged has a home page, the Makefile should +include the URL for that page in the <varname>HOMEPAGE</varname> variable. +The definition of the variable should be placed immediately after the +<varname>MAINTAINER</varname> variable. +</para> +</sect1> + + +<sect1> +<title>How to handle modified distfiles with the 'old' name</title> + +<para> +Sometimes authors of a software package make some modifications after the +software was released, and they put up a new distfile without changing the +package's version number. If a package is already in pkgsrc at that time, +the md5 checksum will no longer match. The correct way to work around this +is to update the package's md5 checksum to match the package on the master +site (beware, any mirrors may not be up to date yet!), and to remove the +old distfile from ftp.NetBSD.org's +<filename>/pub/NetBSD/packages/distfiles</filename> directory. +Furthermore, a mail to the package's author seems appropriate making sure +the distfile was really updated on purpose, and that no trojan horse or so +crept in. +</para> +</sect1> + +<sect1> +<title>What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?</title> +<para> +When compiling the <pkg>pkgtools/pkg_install</pkg> package, you get the error +from make that it doesn't know how to make +<filename>/usr/share/tmac/tmac.andoc</filename>? This +indicates that you don't have installed the <quote>text</quote> set on your machine +(nroff, ...). It is recommended to do that. +</para> + +<para> +In the case of the <pkg>pkgtools/pkg_install</pkg> package, you can get +away with setting <varname>NOMAN=YES</varname> either in the environment +or in <filename>/etc/mk.conf</filename>. +</para> +</sect1> + + +<sect1> +<title>How to handle incrementing versions when fixing an existing +package</title> + +<para> +When making fixes to an existing package it can be useful to change +the version number in <varname>PKGNAME</varname>. To avoid conflicting with +future versions +by the original author, a <quote>nb1</quote>, <quote>nb2</quote>, ... suffix +can be used on package +versions by setting <varname>PKGREVISION=1</varname> (2,. ..). The +<quote>nb</quote> is treated like a <quote>.</quote> by the pkg tools. e.g. +</para> + +<programlisting>DISTNAME= foo-17.42 +PKGREVISION= 9</programlisting> + +<para> +will result in a <varname>PKGNAME</varname> of <quote>foo-17.42nb9</quote>. +</para> + +<para> +When a new release of the package is released, the +<varname>PKGREVISION</varname> should be +removed. e.g. on a new minor release of the above package, things should +be like: +</para> + +<programlisting>DISTNAME= foo-17.43</programlisting> +</sect1> + + +<sect1> +<title>Could not find bsd.own.mk - what's wrong?</title> + +<para> +You didn't install the compiler set, <filename>comp.tgz</filename>, when +you installed your NetBSD machine. Please get it and install it, by +extracting it in <filename>/</filename>: +</para> + +<screen><prompt>#</prompt> <userinput>cd /</userinput> +<prompt>#</prompt> <userinput>tar --unlink -zxvpf .../comp.tgz</userinput></screen> + +<para> +<filename>comp.tgz</filename> is part of every NetBSD release. Get +the one that corresponds to your release (determine via +<command>uname -r</command>). +</para> +</sect1> + + +<sect1> +<title>Restricted packages</title> + +<para> +Some licenses restrict how software may be re-distributed. In order to +satisfy these restrictions, the package system defines five make variables +that can be set to note these restrictions: +</para> + +<itemizedlist> + +<listitem> +<para><varname>RESTRICTED</varname></para> +<para> + This variable should be set whenever a restriction exists + (regardless of its kind). Set this variable to a string + containing the reason for the restriction. +</para> +</listitem> + +<listitem> +<para><varname>NO_BIN_ON_CDROM</varname></para> +<para> + Binaries may not be placed on CD-ROM. Set this variable to + <varname>${RESTRICTED}</varname> whenever a binary package may not + be included on a CD-ROM. +</para> +</listitem> + +<listitem> +<para><varname>NO_BIN_ON_FTP</varname></para> +<para> + Binaries may not be placed on an FTP server. Set this + variable to <varname>${RESTRICTED}</varname> whenever a binary package + may not not be made available on the Internet. +</para> +</listitem> + +<listitem> +<para><varname>NO_SRC_ON_CDROM</varname></para> +<para> + Distfiles may not be placed on CD-ROM. Set this variable to + <varname>${RESTRICTED}</varname> if re-distribution of the source code + or other distfile(s) is not allowed on CD-ROMs. +</para> +</listitem> + +<listitem> +<para><varname>NO_SRC_ON_FTP</varname></para> +<para> + Distfiles may not be placed on FTP. Set this variable to + <varname>${RESTRICTED}</varname> if re-distribution of the source + code or other distfile(s) via the Internet is not allowed. +</para> +</listitem> + +</itemizedlist> + +<para> +Please note that the use of <varname>NO_PACKAGE</varname>, +<varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other generic +make variables to denote restrictions is deprecated, because they +unconditionally prevent users from generating binary packages! +</para> +</sect1> + + +<sect1> +<title>Packages using (n)curses</title> + +<para> +Some packages need curses functionality that wasn't present in NetBSD's own +curses prior to 1.4Y. +</para> + +<para> +If <filename>../../devel/ncurses/buildlink3.mk</filename> is included in +a package's <filename>Makefile</filename>, +then a curses library and headers with ncurses functionality are linked +into <varname>${BUILDLINK_DIR}</varname> at pre-configure time. If +ncurses is actually required, then define <varname>USE_NCURSES</varname> +in the package's <filename>Makefile</filename>: +<screen>USE_NCURSES= # redrawwin</screen> +The comment should indicate which functions are missing. + +</para> +</sect1> + + +<sect1> +<title>Automated security check</title> + +<para> +Please be aware that there can often be bugs in third-party software, +and some of these bugs can leave a machine vulnerable to exploitation +by attackers. In an effort to lessen the exposure, the NetBSD +packages team maintains a database of known-exploits to packages which +have at one time been included in pkgsrc. The database can be +downloaded automatically, and a security audit of all packages +installed on a system can take place. To do this, install the +<pkg>security/audit-packages</pkg> package. It has two components: +</para> + +<orderedlist> + +<listitem> +<para> + <quote>download-vulnerability-list</quote>, an easy way to download a list of the + security vulnerabilities information. This list is kept up to date by + the NetBSD security officer and the NetBSD packages team, and is + distributed from the NetBSD ftp server: +</para> +<para> +<ulink +url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities"/> +</para> +</listitem> + +<listitem> +<para> + <quote>audit-packages</quote>, an easy way to audit the current machine, checking + each vulnerability which is known. If a vulnerable package is + installed, it will be shown by output to stdout, including a + description of the type of vulnerability, and a URL containing more + information. +</para> +</listitem> + +</orderedlist> + +<para> +Use of the audit-packages package is strongly recommended. +</para> + +<para> +The following message is displayed as part of the audit-packages +installation procedure: +</para> + +<screen> +====================================================================== +You may wish to have the vulnerabilities file downloaded daily so that +it remains current. This may be done by adding an appropriate entry +to the root users crontab(5) entry. For example the entry + +# download vulnerabilities file +0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1 + +will update the vulnerability list every day at 3AM. + +In addition, you may wish to run the package audit from the daily +security script. This may be accomplished by adding the following +lines to /etc/security.local + +if [ -x ${PREFIX}/sbin/audit-packages ]; then + ${PREFIX}/sbin/audit-packages +fi +====================================================================== +</screen> + +<para> +Note to package developers: When a vulnerability is found, this should be +noted in +<filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, and after the +commit of that file, it should be copied to both +<filename>/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</filename> +and +<filename>/pub/NetBSD/packages/distfiles/vulnerabilities</filename> on +ftp.NetBSD.org by +<filename>localsrc/security/advisories/Makefile</filename>. +</para> +</sect1> + + +<sect1> +<title>What's the proper way to create an account from a package?</title> + +<para> +There are two make variables used to control the creation of package-specific +groups and users at pre-install time. The first is +<varname>PKG_GROUPS</varname>, which is a +list of group[:groupid] elements, where the groupid is optional. The second +is <varname>PKG_USERS</varname>, which is a list of elements of the form: +</para> + +<programlisting>user:group[:[userid][:[description][:[home][:shell]]]]</programlisting> + +<para> +where only the user and group are required, the rest being optional. A +simple example is: +</para> + +<programlisting>PKG_GROUPS= foogroup +PKG_USERS= foouser:foogroup</programlisting> + +<para> +A more complex example is that creates two groups and two users is: +</para> + +<programlisting>PKG_GROUPS= group1 group2:1005 +PKG_USERS= first:group1::First\\ User \ + second:group2::Second\\ User:/home/second:${SH}</programlisting> + +<para> +By default, a new user will have home directory +<filename>/nonexistent</filename>, and login shell +<filename>/sbin/nologin</filename> unless they are specified as part of +the user element. +</para> + +<para> +The package Makefile must also set +<varname>USE_PKGINSTALL=YES</varname>. This will cause the users and groups +to be created at pre-install time, and the admin will be prompted to remove +them at post-deinstall time. Automatic creation of the users and groups +can be toggled on and off by setting the environment variable +<varname>PKG_CREATE_USERGROUP</varname> prior to package installation. +</para> +</sect1> + + +<sect1> +<title>How to handle compiler bugs</title> + +<para> +Some source files trigger bugs in the compiler, based on combinations +of compiler version and architecture and almost always relation to +optimisation being enabled. Common symptoms are gcc internal errors +or never finishing compiling a file. +</para> + +<para> +Typically a workaround involves testing the <varname>MACHINE_ARCH</varname> +and compiler version, disabling optimisation for that +file/<varname>MACHINE_ARCH</varname>/compiler +combination, and documenting it in <filename>doc/HACKS</filename>. See +<filename>doc/HACKS</filename> for examples. +</para> +</sect1> + + +<sect1 id="features.info-files"> +<title>Packages providing info files</title> + +<para> +Some packages install info files or use the <quote>makeinfo</quote> +or <quote>install-info</quote> commands. Each of the info files: +<itemizedlist> +<listitem>is considered to be installed in the directory + <filename>${PREFIX}/${INFO_DIR}</filename>,</listitem> +<listitem>is registered in the Info directory file + <filename>${PREFIX}/${INFO_DIR}/dir</filename>,</listitem> +<listitem>and must be listed as a filename in the + <varname>INFO_FILES</varname> variable in the package + Makefile.</listitem> +</itemizedlist> +</para> + +<para> +<varname>INFO_DIR</varname> defaults to <quote>info</quote> and can be +overridden in the package Makefile. <filename>INSTALL</filename> and +<filename>DEINSTALL</filename> scripts will be generated to handle +registration of the info files in the Info directory file. The +<quote>install-info</quote> command used for the info files registration is +either provided by the system, or by a special purpose package +automatically added as dependency if needed. +</para> + +<para> +A package which needs the <quote>makeinfo</quote> command at build +time must define the variable <varname>USE_MAKEINFO</varname> in its +Makefile. If a minimum version of the <quote>makeinfo</quote> command +is needed it should be noted with the <varname>TEXINFO_REQD</varname> +variable in the package <filename>Makefile</filename>. By default, a +minimum version of 3.12 is required. If the system does not provide a +<command>makeinfo</command> command or if it does not match the required +minimum, a build dependency on the <pkg>devel/gtexinfo</pkg> package +will be added automatically. +</para> + +<para> +The build and installation process of the software provided by the package +should not use the <command>install-info</command> command as the +registration of info files is the task of the package +<filename>INSTALL</filename> script, and it must use the appropriate +<command>makeinfo</command> command. +</para> + +<para> +To achieve this goal the pkgsrc infrastructure creates overriding scripts +for the <command>install-info</command> and <command>makeinfo</command> +commands in a directory listed early in <varname>PATH</varname>. +</para> + +<para> +The script overriding <command>install-info</command> has no effect except +the logging of a message. The script overriding <command>makeinfo</command> +logs a message and according to the value of <varname>USE_MAKEINFO</varname> +and <varname>TEXINFO_REQD</varname> either run the appropriate +<command>makeinfo</command> command or exit on error. +</para> +</sect1> + +<sect1> +<title>Packages whose distfiles aren't available for plain downloading</title> + +<para> +If you need to download from a dynamic URL you can set +<varname>DYNAMIC_MASTER_SITES</varname> +and a <command>make fetch</command> will call +<filename>files/getsite.sh</filename> with the name of each file +to download as an argument, expecting it to output the URL of the directory +from which to download it. <pkg>graphics/ns-cult3d</pkg> is an example of this usage. +</para> + +<para> +If the download can't be automated, because the user must submit personal +information to apply for a password, or must pay for the source, or whatever, +you can set <varname>_FETCH_MESSAGE</varname> to a macro which displays +a message explaining the situation. <varname>_FETCH_MESSAGE</varname> must +be executable shell commands, not just a message. (Generally, it executes +<varname>${ECHO}</varname>). As of this writing, the following +packages use this: <pkg>audio/realplayer</pkg>, +<pkg>cad/simian</pkg>, <pkg>devel/ipv6socket</pkg>, +<pkg>emulators/vmware-module</pkg>, +<pkg>fonts/acroread-jpnfont</pkg>, +<pkg>sysutils/storage-manager</pkg>, +<pkg>www/ap-aolserver</pkg>, <pkg>www/openacs</pkg>. Try to be consistent +with them. +</para> +</sect1> + +<sect1> +<title>Configuration files handling and placement</title> + +<para> +The global variable <varname>PKG_SYSCONFBASE</varname> (and some others) +can be set by the system administrator in <filename>/etc/mk.conf</filename> +to define the place where +configuration files get installed. Therefore, packages must be adapted to +support this feature. Keep in mind that you should only install files that +are strictly necessary in the configuration directory, files that can +go to <filename>$PREFIX/share</filename> should go there. +</para> + +<para> +We will take a look at available variables first +(<filename>bsd.pkg.mk</filename> contains more +information). <varname>PKG_SYSCONFDIR</varname> is where the +configuration files for a package +may be found (that is, the full path, e.g. <filename>/etc</filename> +or <filename>/usr/pkg/etc</filename>). This +value may be customized in various ways: +</para> + +<orderedlist> + +<listitem> +<para> + <varname>PKG_SYSCONFBASE</varname> is the main config directory under + which all package configuration files are to be found. Users will + typically want to set it to <filename>/etc</filename>, or accept the + default location of <filename>$PREFIX/etc</filename>. +</para> +</listitem> + +<listitem> +<para> + <varname>PKG_SYSCONFSUBDIR</varname> is the subdirectory of + <varname>PKG_SYSCONFBASE</varname> under which + the configuration files for a particular package may be found. Defaults + to <varname>${SYSCONFBASE}</varname>. +</para> +</listitem> + +<listitem> +<para> + <varname>PKG_SYSCONFVAR</varname> is the special suffix used to + distinguish any overriding values for a particular package + (see next item). It defaults to <varname>${PKGBASE}</varname>, but + for a collection of related packages that should all have the same + <varname>PKG_SYSCONFDIR</varname> value, it can be set in each of + the package Makefiles to a common value. +</para> +</listitem> + +<listitem> +<para> + <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> overrides the value of + <varname>${PKG_SYSCONFDIR}</varname> for packages with the same value + for <varname>PKG_SYSCONFVAR</varname>. +</para> + +<para> + As an example, all the various KDE packages may want to set + <varname>PKG_SYSCONFVAR</varname> to <quote>kde</quote> so admins can + set <varname>PKG_SYSCONFDIR.kde</varname> in + <filename>/etc/mk.conf</filename> to define where to install KDE + config files. +</para> +</listitem> + +</orderedlist> + +<para> +Programs' configuration directory should be defined during the configure +stage. Packages that use GNU autoconf can usually do this by using the +<quote>--sysconfdir</quote> parameter, but this brings some problems as +we will see now. +When you change this pathname in packages, you should not allow them to +install files in that directory directly. Instead they need to install +those files under <filename>share/examples/${PKGNAME}</filename> so +<filename>PLIST</filename> can register them. +</para> + +<para> +Once you have the required configuration files in place (under the +<filename>share/examples</filename> directory) the variable +<varname>CONF_FILES</varname> should be set to copy +them into <varname>PKG_SYSCONFDIR</varname>. The contents of this variable +is formed by pairs +of filenames; the first element of the pair specifies the file inside the +examples directory (registered by <filename>PLIST</filename>) and the +second element specifies +the target file. This is done this way to allow binary packages to place +files in the right directory using +<filename>INSTALL</filename>/<filename>DEINSTALL</filename> scripts which are +created automatically. The package <filename>Makefile</filename> must also +set <varname>USE_PKGINSTALL=YES</varname> to use +these automatically generated scripts. The automatic copying of config +files can be toggled by setting the environment variable +<varname>PKG_CONFIG</varname> prior to package installation. +</para> + +<para> +Here is an example, taken from mail/mutt/Makefile: +</para> + +<programlisting>EGDIR= ${PREFIX}/share/doc/mutt/samples +CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc</programlisting> + +<para> +As you can see, this package installs configuration files inside +<varname>EGDIR</varname>, which are registered by +<filename>PLIST</filename>. After that, the variable +<varname>CONF_FILES</varname> lists +the installed file first and then the target file. Users will also get an +automatic message when files are installed using this method. +</para> +</sect1> + + +<sect1> +<title>Packages providing login shells</title> + +<para> +If the purpose of the package is to provide a login shell, the variable +<varname>PKG_SHELL</varname> should contain the full pathname of the +shell executable installed by this package. The package +<filename>Makefile</filename> must also set +<varname>USE_PKGINSTALL=YES</varname> to use the automatically generated +<filename>INSTALL</filename>/<filename>DEINSTALL</filename> scripts. +</para> + +<para> +An example taken from shells/zsh: +</para> + +<programlisting>USE_PKGINSTALL= YES +... +PKG_SHELL= ${PREFIX}/bin/zsh</programlisting> + +<para> +The shell is registered into <filename>/etc/shells</filename> file automatically in the +post-install target by the generated <filename>INSTALL</filename> script +and removed in the deinstall +target by the <filename>DEINSTALL</filename> script. +</para> +</sect1> + + +<sect1> +<title>Packages providing locale catalogues</title> + +<para> +If the package provides its own locale catalogues, the variable +<varname>USE_PKGLOCALEDIR</varname> should be defined. It will ensure +that the package's <filename>Makefile</filename> template files are fixed +and point to the correct locale directories +(which may vary, depending on OS), if necessary. See <xref +linkend="plist.misc"/> for details about <varname>PKGLOCALEDIR</varname>. +This functionality is buildlink3-only. +</para> +</sect1> + + +<sect1> +<title>Using 'sudo' with pkgsrc</title> + +<para> +When installing packages as non-root user and using the just-in-time +su(1) feature of pkgsrc, it can become annoying to type in the root +password for each required package installed. To avoid this, the sudo +package can be used, which does password caching over a limited time. +To use it, install sudo (either as binary package or from +<pkg>security/sudo</pkg>) and then put the following +into your <filename>/etc/mk.conf</filename>: +</para> + +<programlisting>SU_CMD=/usr/pkg/bin/sudo /bin/sh -c</programlisting> +</sect1> + + +<sect1> +<title>Packages containing perl scripts</title> + +<para> +If your package contains interpreted perl scripts, set +<varname>REPLACE_PERL</varname> to ensure that the proper interpreter +path is set. <varname>REPLACE_PERL</varname> should contain a list of +scripts, relative to <varname>WRKSRC</varname>, that you want adjusted. +</para> +</sect1> + +<sect1> +<title>Packages with hardcoded paths to other interpreters</title> + +<para> +Your package may also contain scripts with hardcoded paths to other +interpreters besides (or as well as) perl. To correct the full +pathname to the script interpreter, you need to set the following +definitions in your <filename>Makefile</filename> (we shall use +<command>tclsh</command> in this example): + +<programlisting>REPLACE_INTERPRETER+= tcl +_REPLACE.tcl.old= .*/bin/tclsh +_REPLACE.tcl.new= ${PREFIX}/bin/tclsh +_REPLACE_FILES.tcl= ...list of tcl scripts which need to be fixed, + relative to ${WRKSRC}, just as in REPLACE_PERL</programlisting> +</para> +</sect1> + +<sect1> +<title>Utilities for package management (pkgtools)</title> + +<para> +The directory pkgtools contains a number of useful utilities. This section +attempts only to make the reader aware of the utilities and when they might +be useful, and not to duplicate the documentation that comes with each +package. +</para> + +<para> +Utilities used by pkgsrc (automatically installed when needed): +<itemizedlist> +<listitem>x11-links + <para> + symlinks for use by buildlink + </para> +</listitem> +</itemizedlist> +</para> + +<para> +OS tool augmentation (automatically installed when needed): +<itemizedlist> +<listitem>digest + <para> + calculates SHA1 checksums (and other kinds) + </para> +</listitem> +<listitem>libnbcompat + <para> + compat library for pkg tools + </para> +</listitem> +<listitem>mtree + <para> + installed on non-BSD systems due to lack of native mtree + </para> +</listitem> +<listitem>pkg_install + <para> + up-to-date replacement for /usr/sbin/pkg_install, or for + use on operating systems where pkg_install is not present + </para> +</listitem> +</itemizedlist> +</para> + +<para> +Utilities used by pkgsrc (not automatically installed): +<itemizedlist> +<listitem>pkg_tarup + <para> + create a binary package from an already-installed package. + used by 'make replace' to save the old package + </para> +</listitem> +<listitem>xpkgwedge + <para> + put X11 packages someplace else (see above) + </para> +</listitem> +</itemizedlist> +</para> + +<para> +Utilities for keeping track of installed packages, being up to date, etc: +<itemizedlist> +<listitem>pkgchk + <para> + installs pkg_chk, which reports on packages whose installed + versions do not match the latest pkgsrc entries + </para> +</listitem> +<listitem>pkgdep + <para> + makes dependency graphs of packages, to aid in choosing a + strategy for updating + </para> +</listitem> +<listitem>pkgdepgraph + <para> + make graph from above (uses graphviz) + </para> +</listitem> +<listitem>pkglint + <para> + This provides two distinct abilities: + check a pkgsrc entry for correctness (pkglint) + check for and remove out-of-date distfiles and binary + packages (lintpkgsrc) + </para> +</listitem> +<listitem>pkgsurvey + <para> + report what packages you have installed + </para> +</listitem> +</itemizedlist> +</para> + +<para> +Utilities for people maintaining or creating individual packages: +<itemizedlist> +<listitem>pkgdiff + <para> + automate making and maintaining patches for a package + </para> +</listitem> +<listitem>rpm2pkg, url2pkg + <para> + aids in converting to pkgsrc + </para> +</listitem> +<listitem>gensolpkg + <para> + convert pkgsrc to a Solaris package + </para> +</listitem> +</itemizedlist> +</para> + +<para> +Utilities for people maintaining pkgsrc (or more obscure pkg utilities) +<itemizedlist> +<listitem>pkgconflict + <para> + find packages that conflict but aren't marked as such + </para> +</listitem> +<listitem>pkgcomp + <para> + build packages in a chrooted area + </para> +</listitem> +<listitem>libkver + <para> + spoof kernel version for chrooted cross builds + </para> +</listitem> +</itemizedlist> +</para> + +</sect1> + +<sect1> +<title>How to use pkgsrc as non-root</title> +<para> +If you want to use pkgsrc as non-root user, you can set some variables +to make pkgsrc work under these conditions. Please see +<ulink +url="http://mail-index.netbsd.org/tech-pkg/2003/09/27/0023.html">this +message</ulink> for more details. +</para> +</sect1> + + +<sect1> +<title>Packages that cannot or should not be built</title> + +<para> +There are several reasons why a package might be instructed to not +build under certain circumstances. If the package builds and runs +on most platforms, the exceptions should be noted with +<varname>NOT_FOR_PLATFORM</varname>. If the package builds and runs on +a small handful of platforms, set <varname>ONLY_FOR_PLATFORM</varname> +instead. If the package should be skipped (for example, because it +provides functionality already provided by the system), set +<varname>PKG_SKIP_REASON</varname> to a descriptive message. If +the package should fail because some preconditions are not met, +set <varname>PKG_FAIL_REASON</varname> to a descriptive message. +</para> + +<para> +<varname>IGNORE</varname> is deprecated because it didn't provide enough +information to determine whether the build should fail. +</para> +</sect1> + +</chapter> diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml new file mode 100644 index 00000000000..313080b7355 --- /dev/null +++ b/doc/guide/files/fixes.xml @@ -0,0 +1,1425 @@ +<!-- $NetBSD: fixes.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="fixes"> <?dbhtml filename="fixes.html"?> + <title>Notes on fixes for packages</title> + + <sect1> + <title>General operation</title> + + <sect2> + <title>How to pull in variables from /etc/mk.conf</title> + + <para> The problem with package-defined variables that can be + overridden via <varname>MAKECONF</varname> or + <filename>/etc/mk.conf</filename> is that &man.make.1; expands a + variable as it is used, but evaluates preprocessor like + statements (.if, .ifdef and .ifndef) as they are read. So, to + use any variable (which may be set in + <filename>/etc/mk.conf</filename>) in one of the .if* + statements, the file <filename>/etc/mk.conf</filename> must be + included before that .if* statement. </para> + + <para> Rather than have a number of ad-hoc ways of including + <filename>/etc/mk.conf</filename>, should it exist, or + <varname>MAKECONF</varname>, should it exist, include the + <filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package + Makefile before any preprocessor-like .if, .ifdef, or .ifndef + statements: </para> + + <programlisting>.include "../../mk/bsd.prefs.mk" + + .if defined(USE_MENUS) + ... + .endif</programlisting> + + <para> If you wish to set the <varname>CFLAGS</varname> variable + in <filename>/etc/mk.conf</filename> please make sure to use: + + <programlisting>CFLAGS+= -your -flags</programlisting> + + Using <varname>CFLAGS=</varname> (i.e. without the + <quote>+</quote>) may lead to problems with packages that need + to add their own flags. Also, you may want to take a look at + the <pkg>devel/cpuflags</pkg> package if you're interested in + optimization for the current CPU. </para> + </sect2> + + + <sect2> + <title>Restricted packages</title> + + <para> Some licenses restrict how software may be re-distributed. + In order to satisfy these restrictions, the package system + defines five make variables that can be set to note these + restrictions: </para> + + <itemizedlist> + <listitem> + <para><varname>RESTRICTED</varname></para> + + <para> This variable should be set whenever a restriction + exists (regardless of its kind). Set this variable to a + string containing the reason for the restriction. </para> + </listitem> + + <listitem> + <para><varname>NO_BIN_ON_CDROM</varname></para> + + <para> Binaries may not be placed on CD-ROM. Set this + variable to <varname>${RESTRICTED}</varname> whenever a + binary package may not be included on a CD-ROM. </para> + </listitem> + + <listitem> + <para><varname>NO_BIN_ON_FTP</varname></para> + + <para> Binaries may not be placed on an FTP server. Set + this variable to <varname>${RESTRICTED}</varname> + whenever a binary package may not not be made available + on the Internet. </para> + </listitem> + + <listitem> + <para><varname>NO_SRC_ON_CDROM</varname></para> + + <para> Distfiles may not be placed on CD-ROM. Set this + variable to <varname>${RESTRICTED}</varname> if + re-distribution of the source code or other distfile(s) is + not allowed on CD-ROMs. </para> + </listitem> + + <listitem> + <para><varname>NO_SRC_ON_FTP</varname></para> + + <para> Distfiles may not be placed on FTP. Set this variable + to <varname>${RESTRICTED}</varname> if re-distribution of + the source code or other distfile(s) via the Internet is not + allowed. </para> + </listitem> + </itemizedlist> + + <para> Please note that the use of <varname>NO_PACKAGE</varname>, + <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other + generic make variables to denote restrictions is deprecated, + because they unconditionally prevent users from generating + binary packages! </para> + </sect2> + + + <sect2 id="dependencies"> + <title>Handling dependencies</title> + + <para> Your package may depend on some other package being present + - and there are various ways of expressing this + dependency. pkgsrc supports the <varname>BUILD_DEPENDS</varname> + and <varname>DEPENDS</varname> definitions, as well as + dependencies via <filename>buildlink3.mk</filename>, which is + the preferred way to handle dependencies, and which uses the + variables named above. See <xref linkend="buildlink"/> for more + information. </para> + + <para> The basic difference between the two variables is as + follows: The <varname>DEPENDS</varname> definition registers + that pre-requisite in the binary package so it will be pulled in + when the binary package is later installed, whilst the + <varname>BUILD_DEPENDS</varname> definition does not, marking a + dependency that is only needed for building the package. + </para> + + <para> This means that if you only need a package present whilst + you are building, it should be noted as a + <varname>BUILD_DEPENDS</varname>. </para> + + <para> The format for a <varname>BUILD_DEPENDS</varname> and a + <varname>DEPENDS</varname> definition is: </para> + + <programlisting><pre-req-package-name>:../../<category>/<pre-req-package></programlisting> + + <para> Please note that the <quote>pre-req-package-name</quote> + may include any of the wildcard version numbers recognised by + &man.pkg.info.1;. </para> + + <orderedlist> + <listitem> + <para> If your package needs another package's binaries or + libraries to build or run, and if that package has a + <filename>buildlink3.mk</filename> file available, use it: + </para> + + <programlisting> + .include "../../graphics/jpeg/buildlink3.mk" + </programlisting> + </listitem> + + <listitem> + <para> If your package needs to use another package to build + itself and there is no <filename>buildlink3.mk</filename> + file available, use the <varname>BUILD_DEPENDS</varname> + definition: </para> + + <programlisting>BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf</programlisting> + </listitem> + + <listitem> + <para> If your package needs a library with which to link and + again there is no <filename>buildlink3.mk</filename> file + available, this is specified using the + <varname>DEPENDS</varname> definition. An example of this + is the <pkg>print/lyx</pkg> package, which uses the xpm + library, version 3.4j to build: </para> + + <programlisting>DEPENDS+= xpm-3.4j:../../graphics/xpm</programlisting> + + <para> You can also use wildcards in package dependences: + </para> + + <programlisting>DEPENDS+= xpm-[0-9]*:../../graphics/xpm</programlisting> + + <para> Note that such wildcard dependencies are retained when + creating binary packages. The dependency is checked when + installing the binary package and any package which matches + the pattern will be used. Wildcard dependencies should be + used with care. </para> + + <para> The <quote>-[0-9]*</quote> should be used instead of + <quote>-*</quote> to avoid potentially ambiguous matches + such as <quote>tk-postgresql</quote> matching a + <quote>tk-*</quote> <varname>DEPENDS</varname>. </para> + + <para>Wildcards can also be used to specify that a package + will only build against a certain minimum version of a + pre-requisite: </para> + + <programlisting>DEPENDS+= tiff>=3.5.4:../../graphics/tiff</programlisting> + + <para> This means that the package will build against version + 3.5.4 of the tiff library or newer. Such a dependency may + be warranted if, for example, the API of the library has + changed with version 3.5.4 and a package would not compile + against an earlier version of tiff. </para> + + <para> Please note that such dependencies should only be + updated if a package requires a newer pre-requisite, but + not to denote recommendations such as security updates or + ABI changes that do not prevent a package from building + correctly. Such recommendations can be expressed using + <varname>RECOMMENDED</varname>: </para> + + <programlisting>RECOMMENDED+= tiff>=3.6.1:../../graphics/tiff</programlisting> + + <para> In addition to the above <varname>DEPENDS</varname> + line, this denotes that while a package will build against + tiff>=3.5.4, at least version 3.6.1 is recommended. + <varname>RECOMMENDED</varname> entries will be turned into + dependencies unless explicitly ignored (in which case a + warning will be printed). Packages that are built with + recommendations ignored may not be uploaded to + ftp.NetBSD.org by developers and should not be used across + different systems that may have different versions of binary + packages installed. </para> + + <para> For security fixes, please update the package + vulnerabilities file as well as setting + <varname>RECOMMENDED</varname>, see <xref + linkend="security-handling"/> for more + information. </para> + </listitem> + + <listitem> + <para> If your package needs some executable to be able to run + correctly and if there's agail no + <filename>buildlink3.mk</filename> file, this is specified + using the <varname>DEPENDS</varname> variable. The + <pkg>print/lyx</pkg> package needs to be able to execute the + latex binary from the teTeX package when it runs, and that + is specified: </para> + + <programlisting>DEPENDS+= teTeX-[0-9]*:../../print/teTeX</programlisting> + + <para> The comment about wildcard dependencies from previous + paragraph applies here, too. </para> + </listitem> + </orderedlist> + + <para> If your package needs files from another package to build, + see the first part of the <quote>do-configure</quote> target + <pkg>print/ghostscript5</pkg> package (it relies on the jpeg + sources being present in source form during the build): </para> + + <programlisting>if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \ + cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} extract; \ + fi</programlisting> + + <para> If you build any other packages that way, please make sure + the working files are deleted too when this package's working + files are cleaned up. The easiest way to do so is by adding a + pre-clean target: </para> + + <programlisting>pre-clean: + cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} clean</programlisting> + + <para> Please also note the <varname>BUILD_USES_MSGFMT</varname> + and <varname>BUILD_USES_GETTEXT_M4</varname> definitions, which + are provided as convenience definitions. The former works out + whether msgfmt(1) is part of the base system, and, if it isn't, + installs the <pkg>devel/gettext</pkg> package. The latter adds + a build dependency on either an installed version of an older + gettext package, or if it isn't, installs the + <pkg>devel/gettext-m4</pkg> package. </para> + </sect2> + + + <sect2> + <title>Handling conflicts with other packages</title> + + <para> Your package may conflict with other packages a user might + already have installed on his system, e.g. if your package + installs the same set of files like another package in our + pkgsrc tree. </para> + + <para> In this case you can set <varname>CONFLICTS</varname> to a + space separated list of packages (including version string) your + package conflicts with. </para> + + <para> For example <pkg>x11/Xaw3d</pkg> and <pkg>x11/Xaw-Xpm</pkg> + install provide the same shared library, thus you set in + <filename>pkgsrc/x11/Xaw3d/Makefile</filename>: </para> + + <programlisting>CONFLICTS= Xaw-Xpm-[0-9]*</programlisting> + + <para> and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>: + </para> + + <programlisting>CONFLICTS= Xaw3d-[0-9]*</programlisting> + + <para> Packages will automatically conflict with other packages + with the name prefix and a different version + string. <quote>Xaw3d-1.5</quote> e.g. will automatically + conflict with the older version <quote>Xaw3d-1.3</quote>. + </para> + </sect2> + + + <sect2> + <title>Packages that cannot or should not be built</title> + + <para> + There are several reasons why a package might be instructed to not + build under certain circumstances. If the package builds and runs + on most platforms, the exceptions should be noted with + <varname>NOT_FOR_PLATFORM</varname>. If the package builds and + runs on a small handful of platforms, set + <varname>ONLY_FOR_PLATFORM</varname> instead. If the package + should be skipped (for example, because it provides functionality + already provided by the system), set + <varname>PKG_SKIP_REASON</varname> to a descriptive message. If + the package should fail because some preconditions are not met, + set <varname>PKG_FAIL_REASON</varname> to a descriptive message. + </para> + + <para> <varname>IGNORE</varname> is deprecated because it didn't + provide enough information to determine whether the build should + fail. + </para> + </sect2> + + + <sect2> + <title>Packages which should not be deleted, once installed</title> + + <para>To ensure that a package may not be deleted, once it has been + installed, the <varname>PKG_PRESERVE</varname> definition should + be set in the package Makefile. This will be carried into any + binary package that is made from this pkgsrc entry. A + <quote>preserved</quote> package will + not be deleted using &man.pkg.delete.1; unless the + <quote>-f</quote> option is used. </para> + </sect2> + + + <sect2 id="security-handling"> + <title>Handling packages with security problems</title> + + <para> When a vulnerability is found, this should be noted in + <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, + and after the commit of that file, it should be copied to both + <filename>/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</filename> + and + <filename>/pub/NetBSD/packages/distfiles/vulnerabilities</filename> + on ftp.NetBSD.org using + <filename>localsrc/security/advisories/Makefile</filename>. In + addition, if a <filename>buildlink3.mk</filename> file exists + for an affected package, bumping <varname>PKGREVISION</varname> + and creating a corresponding + <varname>BUILDLINK_RECOMMENDED.<replaceable>pkg</replaceable></varname> + entry should be considered. See <xref linkend="buildlink"/> for + more information about writing + <filename>buildlink3.mk</filename> files and + <varname>BUILDLINK_*</varname> definitions. </para> + + <para> Also, if the fix should be applied to the stable pkgsrc + branch, be sure to submit a pullup request! </para> + </sect2> + + + <sect2> + <title>How to handle compiler bugs</title> + + <para> Some source files trigger bugs in the compiler, based on + combinations of compiler version and architecture and almost + always relation to optimisation being enabled. Common symptoms + are gcc internal errors or never finishing compiling a file. + </para> + + <para> Typically a workaround involves testing the + <varname>MACHINE_ARCH</varname> and compiler version, disabling + optimisation for that + file/<varname>MACHINE_ARCH</varname>/compiler combination, and + documenting it in <filename>pkgsrc/doc/HACKS</filename>. See + that file for a number of examples! </para> + </sect2> + + + <sect2> + <title>How to handle incrementing versions when fixing an existing package</title> + + <para> When making fixes to an existing package it can be useful + to change the version number in <varname>PKGNAME</varname>. To + avoid conflicting with future versions by the original author, a + <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used + on package versions by setting <varname>PKGREVISION=1</varname> + (2, ...). The <quote>nb</quote> is treated like a + <quote>.</quote> by the pkg tools. e.g. </para> + + <programlisting> DISTNAME= foo-17.42 + PKGREVISION= 9</programlisting> + + <para> will result in a <varname>PKGNAME</varname> of + <quote>foo-17.42nb9</quote>. </para> + + <para> When a new release of the package is released, the + <varname>PKGREVISION</varname> should be removed. e.g. on a new + minor release of the above package, things should be like: + </para> + + <programlisting>DISTNAME= foo-17.43</programlisting> + </sect2> + + + <sect2> + <title>Portability of packages</title> + + <para>One appealing feature of pkgsrc is that it runs on many different + platforms. As a result, it is important to ensure, where possible, + that packages in pkgsrc are portable. There are some particular + details you should pay attention to while working on pkgsrc.</para> + + <sect3> + <title>${INSTALL}, ${INSTALL_DATA_DIR}, ...</title> + + <para>The BSD-compatible <command>install</command> supplied with some + operating systems will not perform more than one operation at a time. + As such, you should call <quote>${INSTALL}</quote>, etc. like this:</para> + + <programlisting>${INSTALL_DATA_DIR} ${PREFIX}/dir1 +${INSTALL_DATA_DIR} ${PREFIX}/dir2</programlisting> + </sect3> + + </sect2> + </sect1> + + + <sect1> + <title>Possible downloading issues</title> + + <sect2> + <title>Packages whose distfiles aren't available for plain downloading</title> + + <para> If you need to download from a dynamic URL you can set + <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make + fetch</command> will call <filename>files/getsite.sh</filename> + with the name of each file to download as an argument, expecting + it to output the URL of the directory from which to download + it. <pkg>graphics/ns-cult3d</pkg> is an example of this usage. + </para> + + <para> If the download can't be automated, because the user must + submit personal information to apply for a password, or must pay + for the source, or whatever, you can set + <varname>_FETCH_MESSAGE</varname> to a macro which displays a + message explaining the + situation. <varname>_FETCH_MESSAGE</varname> must be executable + shell commands, not just a message. (Generally, it executes + <varname>${ECHO}</varname>). As of this writing, the following + packages use this: <pkg>audio/realplayer</pkg>, + <pkg>cad/simian</pkg>, <pkg>devel/ipv6socket</pkg>, + <pkg>emulators/vmware-module</pkg>, + <pkg>fonts/acroread-jpnfont</pkg>, + <pkg>sysutils/storage-manager</pkg>, + <pkg>www/ap-aolserver</pkg>, <pkg>www/openacs</pkg>. Try to be + consistent with them. </para> + </sect2> + + + <sect2> + <title>How to handle modified distfiles with the 'old' name</title> + + <para> Sometimes authors of a software package make some + modifications after the software was released, and they put up a + new distfile without changing the package's version number. If a + package is already in pkgsrc at that time, the md5 checksum will + no longer match. The correct way to work around this is to + update the package's md5 checksum to match the package on the + master site (beware, any mirrors may not be up to date yet!), + and to remove the old distfile from + ftp.NetBSD.org's + <filename>/pub/NetBSD/packages/distfiles</filename> directory. + Furthermore, a mail to the package's author seems appropriate + making sure the distfile was really updated on purpose, and that + no trojan horse or so crept in. </para> + </sect2> + </sect1> + + + <sect1> + <title>Configuration gotchas</title> + + <sect2 id="fixes.libtool"> + <title>Shared libraries - libtool</title> + + <para>pkgsrc supports many different machines, with different + object formats like a.out and ELF, and varying abilities to do + shared library and dynamic loading at all. To accompany this, + varying commands and options have to be passed to the + compiler, linker, etc. to get the Right Thing, which can be + pretty annoying especially if you don't have all the machines + at your hand to test things. The <pkg>devel/libtool</pkg> pkg + can help here, as it just <quote>knows</quote> how to build + both static and dynamic libraries from a set of source files, + thus being platform independent.</para> + + <para>Here's how to use libtool in a pkg in seven simple + steps:</para> + + <orderedlist> + <listitem> + <para>Add <varname>USE_LIBTOOL=yes</varname> to the package + Makefile.</para> + </listitem> + + <listitem> + <para>For library objects, use <quote>${LIBTOOL} --mode=compile + ${CC}</quote> in place of <quote>${CC}</quote>. You could even + add it to the definition of <varname>CC</varname>, if only + libraries are being built in a given Makefile. This one command + will build both PIC and non-PIC library objects, so you need not + have separate shared and non-shared library rules.</para> + </listitem> + + <listitem> + <para>For the linking of the library, remove any + <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld + -Bshareable</quote> commands, and instead use:</para> + + <programlisting>${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} -rpath ${PREFIX}/lib -version-info major:minor</programlisting> + + <para>Note that the library is changed to have a + <filename>.la</filename> extension, and the objects are + changed to have a <filename>.lo</filename> + extension. Change <varname>OBJS</varname> as + necessary. This automatically creates all of the + <filename>.a</filename>, + <filename>.so.major.minor</filename>, and ELF symlinks (if + necessary) in the build directory. Be sure to include + <quote>-version-info</quote>, especially when major and + minor are zero, as libtool will otherwise strip off the + shared library version.</para> + + <para> From the libtool manual:</para> + + <programlisting> + So, libtool library versions are described by three integers: + +CURRENT + The most recent interface number that this library implements. + +REVISION + The implementation number of the CURRENT interface. + +AGE + The difference between the newest and oldest interfaces that this + library implements. In other words, the library implements all the + interface numbers in the range from number `CURRENT - AGE' to + `CURRENT'. + + If two libraries have identical CURRENT and AGE numbers, then the +dynamic linker chooses the library with the greater REVISION number. </programlisting> + + <para>The <quote>-release</quote> option will produce + different results for a.out and ELF (excluding symlinks) + in only one case. An ELF library of the form + <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> + will have a symlink of + <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> + on an a.out platform. This is handled + automatically.</para> + + <para>The <quote>-rpath argument</quote> is the install + directory of the library being built.</para> + + <para>In the <filename>PLIST</filename>, include all of the + <filename>.a</filename>, <filename>.la</filename>, and + <filename>.so</filename>, + <filename>.so.<replaceable>major</replaceable></filename> + and + <filename>.so.<replaceable>major</replaceable>.<replaceable>minor</replaceable></filename> + files.</para> + </listitem> + + <listitem> + <para>When linking shared object (<filename>.so</filename>) + files, i.e. files that are loaded via dlopen(3), NOT + shared libraries, use <quote>-module + -avoid-version</quote> to prevent them getting version + tacked on.</para> + + <para>The <filename>PLIST</filename> file gets the + <filename>foo.so</filename> entry.</para> + </listitem> + + <listitem> + <para>When linking programs that depend on these libraries + <emphasis>before</emphasis> they are installed, preface + the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} + --mode=link</quote>, and it will find the correct + libraries (static or shared), but please be aware that + libtool will not allow you to specify a relative path in + -L (such as <quote>-L../somelib</quote>), because it + expects you to change that argument to be the + <filename>.la</filename> file. e.g.</para> + + <programlisting>${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib</programlisting> + + <para>should be changed to:</para> + + <programlisting>${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable></programlisting> + + <para>and it will do the right thing with the libraries.</para> + </listitem> + + <listitem> + <para>When installing libraries, preface the &man.install.1; + or &man.cp.1; command with <quote>${LIBTOOL} + --mode=install</quote>, and change the library name to + <filename>.la</filename>. e.g.</para> + + <programlisting>${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib</programlisting> + + <para>This will install the static <filename>.a</filename>, + shared library, any needed symlinks, and run + &man.ldconfig.8;.</para> + </listitem> + + <listitem> + <para> In your <filename>PLIST</filename>, include all of + the <filename>.a</filename>, <filename>.la</filename>, and + <filename>.so</filename>, <filename>.so.CURRENT</filename> + and <filename>.so.CURRENT.REVISION</filename> files (this + is a change from the previous behaviour). </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Using libtool on GNU packages that already support libtool</title> + + <para>Add <varname>USE_LIBTOOL=yes</varname> to the + package Makefile. This will override the package's own libtool + in most cases. For older libtool using packages, libtool is + made by ltconfig script during the do-configure step; you can + check the libtool script location by doing <command>make + configure; find work*/ -name libtool</command>. </para> + + <para> <varname>LIBTOOL_OVERRIDE</varname> specifies which libtool + scripts, relative to <varname>WRKSRC</varname>, to override. By + default, it is set to <quote>libtool */libtool + */*/libtool</quote>. If this does not match the location of the + package's libtool script(s), set it as appropriate. </para> + + <para> If you do not need <filename>*.a</filename> static + libraries built and installed, then use + <varname>SHLIBTOOL_OVERRIDE</varname> instead. </para> + + <para>If your package makes use of the platform independent library + for loading dynamic shared objects, that comes with libtool + (libltdl), you should include the libtool buildlink3.mk (and + set <varname>USE_BUILDLINK3=YES</varname>).</para> + + <para>Some packages use libtool incorrectly so that the package may not work or + build in some circumstances. Some of the more common errors are:</para> + + <itemizedlist> + <listitem> + <para>The inclusion of a shared object (-module) as a dependent library in an + executable or library. This in itself isn't a problem if one of two things + has been done:</para> + + <orderedlist> + <listitem> + <para>The shared object is named correctly, i.e. + <filename>libfoo.la</filename>, not + <filename>foo.la</filename></para> + </listitem> + + <listitem> + <para>The -dlopen option is used when linking an executable.</para> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>The use of libltdl without the correct calls to initialisation routines. + The function lt_dlinit() should be called and the macro + <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in + executables.</para> + </listitem> + </itemizedlist> + </sect2> + + + <sect2> + <title>GNU Autoconf/Automake</title> + + <para>If a package needs GNU autoconf or automake to be executed + to regenerate the configure script and Makefile.in makefile + templates, then they should be executed in a pre-configure + target. Two Makefile fragments are provided in + <filename>pkgsrc/mk/autoconf.mk</filename> and + <filename>pkgsrc/mk/automake.mk</filename> to help + dealing with these tools. See comments in these files for + details.</para> + + <para> For packages that need only autoconf: </para> + + <programlisting>AUTOCONF_REQD= 2.50 # if default version is not good enough +... + +pre-configure: + cd ${WRKSRC}; ${AUTOCONF} + +... +.include "../../mk/autoconf.mk"</programlisting> + + <para> and for packages that need automake and autoconf: </para> + +<programlisting>AUTOMAKE_REQD= 1.7.1 # if default version is not good enough +... + +pre-configure: + cd ${WRKSRC}; \ + ${ACLOCAL}; \ + ${AUTOHEADER}; \ + ${AUTOMAKE} -a --foreign -i; \ + ${AUTOCONF} + +... +.include "../mk/automake.mk"</programlisting> + + <para> Packages which use GNU Automake will almost certainly + require GNU Make, but that's automatically provided for you in + <filename>mk/automake.mk</filename>. </para> + + <para> There are times when the configure process makes + additional changes to the generated files, which then causes + the build process to try to re-execute the automake sequence. + This is prevented by touching various files in the configure + stage. If this causes problems with your package you can set + <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package + Makefile. </para> + </sect2> + </sect1> + + + <sect1> + <title>Building considerations</title> + + <sect2> + <title>CPP defines</title> + + <para> + To port an application to NetBSD, it's usually necessary for the + compiler to be able to judge the system on which it's compiling, and + we use definitions so that the C pre-processor can do this. + </para> + + <para> + To test whether you are working on a 4.4 BSD-derived system, you + should use the BSD definition, which is defined in + <filename><sys/param.h></filename> on said systems. + </para> + + <programlisting><![CDATA[#include <sys/param.h>]]></programlisting> + + <para>and then you can surround the BSD-specific parts of your + package's C/C++ code using this conditional:</para> + + <programlisting><![CDATA[#if (defined(BSD) && BSD >= 199306) + ... +#endif]]></programlisting> + + <para>Please use the <quote>__NetBSD__</quote> definition sparingly - it + should only apply to features of &os; that are not present in other + 4.4-lite derived BSDs.</para> + </sect2> + </sect1> + + + <sect1> + <title>Package specific actions</title> + + <sect2> + <title>Package configuration files</title> + + <para> Packages should be taught to look for their configuration + files in <varname>${PKG_SYSCONFDIR}</varname>, which is passed + through to the configure and build processes. + <varname>PKG_SYSCONFDIR</varname> may be customized in various + ways by setting other make variables: </para> + + <itemizedlist> + <listitem> + <para> <varname>PKG_SYSCONFBASE</varname> is the main config + directory under which all package configuration files are + to be found. This defaults to + <filename>${PREFIX}/etc</filename>, but may be overridden + in <filename>/etc/mk.conf</filename>.</para> + </listitem> + + <listitem> + <para> <varname>PKG_SYSCONFSUBDIR</varname> is the subdirectory of + <varname>PKG_SYSCONFBASE</varname> under which the + configuration files for a particular package may be found, e.g. + the Apache configuration files may all be found under the + <filename>httpd/</filename> subdirectory of + <varname>${PKG_SYSCONFBASE}</varname>. This should be set in + the package Makefile. + </para> + </listitem> + + <listitem> + <para> By default, + <varname>PKG_SYSCONFDIR</varname> is set to + <varname>${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</varname>, + but this may be overridden by setting + <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> for a + particular package, where <varname>PKG_SYSCONFVAR</varname> + defaults to <varname>${PKGBASE}</varname>. This is not meant to + be set by a package Makefile, but is reserved for users who wish + to override the <varname>PKG_SYSCONFDIR</varname> setting for + a particular package with a special location. + </para> + </listitem> + </itemizedlist> + + <para> The only variables that users should customize are + <varname>PKG_SYSCONFBASE</varname> and <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname>. + Users will typically want to set + <varname>PKG_SYSCONFBASE</varname> to + <filename>/etc</filename>, or to accept the default location + of <filename>${PREFIX}/etc</filename>. </para> + </sect2> + + <sect2> + <title>User Interaction</title> + + <para>Occasionally, packages require interaction from the user, and this can be + in a number of ways:</para> + + <itemizedlist> + <listitem> + <para>help in fetching the distfiles</para> + </listitem> + + <listitem> + <para>help to configure the package before it is built</para> + </listitem> + + <listitem> + <para>help during the build process</para> + </listitem> + + <listitem> + <para>help during the installation of a package</para> + </listitem> + </itemizedlist> + + <para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify + the pkgsrc mechanism of an interactive stage which will be needed, and + this should be set in the package's <filename>Makefile</filename>. e.g.</para> + + <programlisting>INTERACTIVE_STAGE= build</programlisting> + + <para>Multiple interactive stages can be specified:</para> + + <programlisting>INTERACTIVE_STAGE= configure install</programlisting> + </sect2> + + + <sect2> + <title>Handling licenses</title> + + <para>A package may underly a license which the user has or has + not agreed to accept. Usually, packages that underly + well-known Open Source licenses (e.g. the GNU Public License, + GPL) won't have any special license + tags added in pkgsrc which require special action by the user + of such packages, but there are quite a number of other + licenses out there that pkgsrc users may not be able to + follow, for whatever reasons. For these cases, pkgsrc contains + a mechanism to note that a package underlies a certain + license, and the user has to accept the license before the + package can be installed. </para> + + <para> + Placing a certain package under a certain license works by + setting the <varname>LICENSE</varname> variable to a string + identifying the license, e.g. in <pkg>graphics/graphviz</pkg>: + </para> + + <programlisting>LICENSE= graphviz-license</programlisting> + + <para> + When trying to build, the user will get a notice that the + package underlies a license which he hasn't accepted (yet): + </para> + + <programlisting> +&cprompt; <userinput>make</userinput> +===> graphviz-1.12 has an unacceptable license: graphviz-license. +===> To build this package, add this line to your /etc/mk.conf: +===> ACCEPTABLE_LICENSES+=graphviz-license +===> To view the license, enter "/usr/bin/make show-license". +*** Error code 1</programlisting> + + <para> The license can be viewed with <command>make + show-license</command>, and if it is considered appropriate, + the line printed above can be added to + <filename>/etc/mk.conf</filename> to indicate acceptance of + the particular license:</para> + + <programlisting>ACCEPTABLE_LICENSES+=graphviz-license</programlisting> + + <para>When adding a package with a new license, the license + text should be added to <filename>pkgsrc/licenses</filename> + for displaying. A list of known licenses can be seen in this + directory as well as by looking at the list of (commented + out) <varname>ACCEPTABLE_LICENSES</varname> variable + settings in + <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename>.</para> + + <para> Is there is a <emphasis>really</emphasis> pressing need + to accept all licenses at once, like when trying to download + or mirror all distfiles or doing a bulk build to test if all + packages in pkgsrc build, this can be done by setting + <varname>_ACCEPTABLE=yes</varname>. + </para> + </sect2> + + + <sect2> + <title>Creating an account from a package</title> + + <para> There are two make variables used to control the creation + of package-specific groups and users at pre-install time. The + first is <varname>PKG_GROUPS</varname>, which is a list of + group[:groupid] elements, where the groupid is optional. The + second is <varname>PKG_USERS</varname>, which is a list of + elements of the form: </para> + + <programlisting>user:group[:[userid][:[description][:[home][:shell]]]]</programlisting> + + <para> where only the user and group are required, the rest being + optional. A simple example is: </para> + + <programlisting> PKG_GROUPS= foogroup + PKG_USERS= foouser:foogroup</programlisting> + + <para> A more complex example is that creates two groups and two + users is: </para> + + <programlisting> PKG_GROUPS= group1 group2:1005 + PKG_USERS= first:group1::First\\ User \ + second:group2::Second\\ User:/home/second:${SH}</programlisting> + + <para> By default, a new user will have home directory + <filename>/nonexistent</filename>, and login shell + <filename>/sbin/nologin</filename> unless they are specified as + part of the user element. </para> + + <para> The package <filename>Makefile</filename> must also set + <varname>USE_PKGINSTALL=YES</varname>. This will cause the users + and groups to be created at pre-install time, and the admin will + be prompted to remove them at post-deinstall time. Automatic + creation of the users and groups can be toggled on and off by + setting the <varname>PKG_CREATE_USERGROUP</varname> variable + prior to package installation. </para> + </sect2> + + + <sect2> + <title>Installing score files</title> + + <para> Certain packages, most of them in the games category, install + a score file that allows all users on the system to record their + highscores. In order for this to work, the binaries need to be + installed setgid and the score files owned by the appropriate + group and/or owner (traditionally the "games" user/group). The + following variables, documented in more detail in + <filename>mk/bsd.pkg.defaults.mk</filename>, control this + behaviour: <varname>SETGIDGAME</varname>, + <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>, + <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>. </para> + + <para> Note that per default, setgid installation of games is + disabled; setting <varname>SETGIDGAME=YES</varname> will set all + the other variables accordingly. </para> + + <para> A package should therefor never hard code file ownership or + access permissions but rely on <varname>INSTALL_GAME</varname> and + <varname>INSTALL_GAME_DATA</varname> to set these + correctly. </para> + </sect2> + + + <sect2> + <title>Packages providing login shells</title> + + <para> If the purpose of the package is to provide a login shell, + the variable <varname>PKG_SHELL</varname> should contain the + full pathname of the shell executable installed by this + package. The package <filename>Makefile</filename> must also + set <varname>USE_PKGINSTALL=YES</varname> to use the + automatically generated + <filename>INSTALL</filename>/<filename>DEINSTALL</filename> + scripts. </para> + + <para> An example taken from shells/zsh: </para> + + <programlisting> USE_PKGINSTALL= YES + PKG_SHELL= ${PREFIX}/bin/zsh</programlisting> + + <para> + The shell is registered into <filename>/etc/shells</filename> + file automatically in the post-install target by the generated + <filename>INSTALL</filename> script and removed in the deinstall + target by the <filename>DEINSTALL</filename> script. </para> + </sect2> + + + <sect2> + <title>Packages containing perl scripts</title> + + <para> + If your package contains interpreted perl scripts, set + <varname>REPLACE_PERL</varname> to ensure that the proper + interpreter path is set. <varname>REPLACE_PERL</varname> should + contain a list of scripts, relative to + <varname>WRKSRC</varname>, that you want adjusted. </para> + </sect2> + + + <sect2> + <title>Packages with hardcoded paths to other interpreters</title> + + <para> + Your package may also contain scripts with hardcoded paths to + other interpreters besides (or as well as) perl. To correct the + full pathname to the script interpreter, you need to set the + following definitions in your <filename>Makefile</filename> (we + shall use <command>tclsh</command> in this example):</para> + + <programlisting> REPLACE_INTERPRETER+= tcl + _REPLACE.tcl.old= .*/bin/tclsh + _REPLACE.tcl.new= ${PREFIX}/bin/tclsh + _REPLACE_FILES.tcl= ...list of tcl scripts which need to be fixed, + relative to ${WRKSRC}, just as in REPLACE_PERL</programlisting> + </sect2> + + + <sect2> + <title>Packages installing perl modules</title> + + <para>Makefiles of packages providing perl5 modules should include + the Makefile fragment + <filename>../../lang/perl5/module.mk</filename>. It provides a + <command>do-configure</command> target for the standard perl + configuration for such modules as well as various hooks to tune + this configuration. See comments in this file for + details.</para> + + <para>Perl5 modules will install into different places depending + on the version of perl used during the build process. To + address this, pkgsrc will append lines to the + <filename>PLIST</filename> corresponding to the files listed in + the installed <filename>.packlist</filename> file generated by + most perl5 modules. This is invoked by defining + <varname>PERL5_PACKLIST</varname> to a space-separated list of + paths to packlist files, e.g.:</para> + + <programlisting>PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist</programlisting> + + <para>The variables <varname>PERL5_SITELIB</varname>, + <varname>PERL5_SITEARCH</varname>, and + <varname>PERL5_ARCHLIB</varname> represent the three locations + in which perl5 modules may be installed, and may be used by + perl5 packages that don't have a packlist. These three + variables are also substituted for in the + <filename>PLIST</filename>.</para> + </sect2> + + + <sect2 id="faq.info-files"> + <title>Packages installing info files</title> + + <para> Some packages install info files or use the + <quote>makeinfo</quote> or <quote>install-info</quote> + commands. Each of the info files: </para> + + <itemizedlist> + <listitem> + <para>is considered to be installed in the directory + <filename>${PREFIX}/${INFO_DIR}</filename>,</para> + </listitem> + + <listitem> + <para>is registered in the Info directory file + <filename>${PREFIX}/${INFO_DIR}/dir</filename>,</para> + </listitem> + + <listitem> + <para>and must be listed as a filename in the + <varname>INFO_FILES</varname> variable in the package + Makefile.</para> + </listitem> + </itemizedlist> + + <para> <varname>INFO_DIR</varname> defaults to <quote>info</quote> + and can be overridden in the package + Makefile. <filename>INSTALL</filename> and + <filename>DEINSTALL</filename> scripts will be generated to + handle registration of the info files in the Info directory + file. The <quote>install-info</quote> command used for the info + files registration is either provided by the system, or by a + special purpose package automatically added as dependency if + needed. </para> + + <para> A package which needs the <quote>makeinfo</quote> command + at build time must define the variable + <varname>USE_MAKEINFO</varname> in its Makefile. If a minimum + version of the <quote>makeinfo</quote> command is needed it + should be noted with the <varname>TEXINFO_REQD</varname> + variable in the package <filename>Makefile</filename>. By + default, a minimum version of 3.12 is required. If the system + does not provide a <command>makeinfo</command> command or if it + does not match the required minimum, a build dependency on the + <pkg>devel/gtexinfo</pkg> package will be added automatically. + </para> + + <para> The build and installation process of the software provided + by the package should not use the + <command>install-info</command> command as the registration of + info files is the task of the package + <filename>INSTALL</filename> script, and it must use the + appropriate <command>makeinfo</command> command. </para> + + <para> To achieve this goal the pkgsrc infrastructure creates + overriding scripts for the <command>install-info</command> and + <command>makeinfo</command> commands in a directory listed early + in <varname>PATH</varname>. </para> + + <para> The script overriding <command>install-info</command> has + no effect except the logging of a message. The script overriding + <command>makeinfo</command> logs a message and according to the + value of <varname>USE_MAKEINFO</varname> and + <varname>TEXINFO_REQD</varname> either run the appropriate + <command>makeinfo</command> command or exit on error. </para> + </sect2> + + + <sect2> + <title>Packages installing GConf2 data files</title> + + <para> + If a package installs <filename>.schemas</filename> or + <filename>.entries</filename> files, used by GConf2, + you need to take some extra steps to make sure they get registered + in the database: + </para> + + <orderedlist> + <listitem> + <para> Include <filename>../../devel/GConf2/schemas.mk</filename> + instead of its <filename>buildlink3.mk</filename> file. This + takes care of rebuilding the GConf2 database at installation and + deinstallation time, and tells the package where to install + GConf2 data files using some standard configure arguments. It + also disallows any access to the database directly from the + package. </para> + </listitem> + + <listitem> + <para> Ensure that the package installs its + <filename>.schemas</filename> files under + <filename>${PREFIX}/share/gconf/schemas</filename>. If they get + installed under <filename>${PREFIX}/etc</filename>, you will + need to manually patch the package. </para> + </listitem> + + <listitem> + <para> Check the PLIST and remove any entries under the etc/gconf + directory, as they will be handled automatically. See + <xref linkend="faq.conf"/> for more information. </para> + </listitem> + + <listitem> + <para> Define the <varname>GCONF2_SCHEMAS</varname> variable in + your <filename>Makefile</filename> with a list of all + <filename>.schemas</filename> files installed by the package, if + any. Names must not contain any directories in them. </para> + </listitem> + + <listitem> + <para> Define the <varname>GCONF2_ENTRIES</varname> variable in + your <filename>Makefile</filename> with a + list of all <filename>.entries</filename> files installed by the + package, if any. Names must not contain any directories in + them. </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Packages installing scrollkeeper data files</title> + + <para> + If a package installs <filename>.omf</filename> files, used by + scrollkeeper, you need to take some extra steps to make sure they + get registered in the database: + </para> + + <orderedlist> + <listitem> + <para> Include + <filename>../../textproc/scrollkeeper/omf.mk</filename> + instead of its <filename>buildlink3.mk</filename> file. This + takes care of rebuilding the scrollkeeper database at + installation and deinstallation time, and disallows any access + to it directly from the package. + </para> + </listitem> + + <listitem> + <para> Check the PLIST and remove any entries under the + <filename>libdata/scrollkeeper</filename> directory, as they + will be handled automatically. </para> + </listitem> + + <listitem> + <para> Remove the <filename>share/omf</filename> directory from + the PLIST. It will be handled by scrollkeeper. </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Packages installing X11 fonts</title> + + <para> If a package installs font files, you will need to rebuild + the fonts database in the directory where they get installed at + installation and deinstallation time. This can be automatically + done by using <filename>mk/fonts.mk</filename>, which you need to + include in your <filename>Makefile</filename>. </para> + + <para> When the file is included, you can list the directories where + fonts are installed in the + <varname>FONTS_<replaceable>type</replaceable>_DIRS</varname> + variables, where <replaceable>type</replaceable> can be one of + <quote>TTF</quote>, <quote>TYPE1</quote> or <quote>X11</quote>. + Also make sure that the database file + <filename>fonts.dir</filename> is not listed in the PLIST. </para> + + <para> Note that you should not create new directories for fonts; + instead use the standard ones to avoid that the user needs to + manually configure his X server to find them. </para> + </sect2> + + + <sect2> + <title>Packages installing GTK2 modules</title> + + <para>If a package installs gtk2 immodules or loaders, you need to + take some extra steps to get them registered in the GTK2 database + properly: </para> + + <orderedlist> + <listitem> <para> Include + <filename>../../x11/gtk2/modules.mk</filename> instead of its + <filename>buildlink3.mk</filename> file. This takes care of + rebuilding the database at installation and deinstallation time. + </para> + </listitem> + + <listitem> <para> + Set <varname>GTK2_IMMODULES=YES</varname> if + your package installs GTK2 immodules. </para> + </listitem> + + <listitem> <para> + Set <varname>GTK2_LOADERS=YES</varname> if your package installs + GTK2 loaders. </para> + </listitem> + + <listitem> <para> + Patch the package to not touch any of the gtk2 databases directly. + These are: + + <itemizedlist> + <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem> + <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> <para> + Check the PLIST and remove any entries under the + <filename>libdata/gtk-2.0</filename> directory, as they will be + handled automatically. </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Packages installing SGML or XML data</title> + + <para> If a package installs SGML or XML data files that need to be + registered in system-wide catalogs (like DTDs, sub-catalogs, + etc.), you need to take some extra steps: + </para> + + <orderedlist> + <listitem> + <para> Include + <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in + your <filename>Makefile</filename>, which takes care of + registering those files in system-wide catalogs at + installation and deinstallation time. </para> + </listitem> + + <listitem> + <para> Set <varname>SGML_CATALOGS</varname> to the full path of + any SGML catalogs installed by the package. </para> + </listitem> + + <listitem> + <para> Set <varname>XML_CATALOGS</varname> to the full path of + any XML catalogs installed by the package. </para> + </listitem> + + <listitem> + <para> Set <varname>SGML_ENTRIES</varname> to individual entries + to be added to the SGML catalog. These come in groups of + three strings; see xmlcatmgr(1) for more information + (specifically, arguments recognized by the 'add' action). + Note that you will normally not use this variable. </para> + </listitem> + + <listitem> + <para> Set <varname>XML_ENTRIES</varname> to individual entries + to be added to the XML catalog. These come in groups of three + strings; see xmlcatmgr(1) for more information (specifically, + arguments recognized by the 'add' action). Note that you will + normally not use this variable. + </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Packages installing extensions to the MIME database</title> + + <para> If a package provides extensions to the MIME database by + installing <filename>.xml</filename> files inside + <filename>${PREFIX}/share/mime/packages</filename>, you + need to take some extra steps to ensure that the database is kept + consistent with respect to these new files: + </para> + + <orderedlist> + <listitem> + <para> Include + <filename>../../databases/shared-mime-info/mimedb.mk</filename> + (avoid using the <filename>buildlink3.mk</filename> file from + this same directory, which is reserved for inclusion from + other <filename>buildlink3.mk</filename> files). It takes + care of rebuilding the MIME database at installation and + deinstallation time, and disallows any access to it directly + from the package. </para> + </listitem> + + <listitem> + <para> Check the PLIST and remove any entries under the + <filename>share/mime</filename> directory, + <emphasis>except</emphasis> for files saved under + <filename>share/mime/packages</filename>. The former are + handled automatically by + the update-mime-database program, but the later are + package-dependent and must be removed by the package that + installed them in the first place. </para> + </listitem> + + <listitem> + <para> Remove any <filename>share/mime/*</filename> directories + from the PLIST. They will be handled by the shared-mime-info + package. </para> + </listitem> + </orderedlist> + </sect2> + + + <sect2> + <title>Packages using intltool</title> + + <para> If a package uses intltool during its build, include the + <filename>../../textproc/intltool/buildlink3.mk</filename> file, + which forces it to use the intltool package provided by pkgsrc, + instead of the one bundled with the distribution file. + </para> + + <para> This tracks intltool's build-time dependencies and uses the + latest available version; this way, the package benefits of any + bug fixes that may have appeared since it was released. + </para> + </sect2> + + </sect1> + + + <sect1> + <title>Feedback to the author</title> + + <para> If you have found any bugs in the package you make available, + if you had to do special steps to make it run under NetBSD or + if you enhanced the software in various other ways, be sure + to report these changes back to the original author of the + program! With that kind of support, the next release of the + program can incorporate these fixes, and people not using the + NetBSD packages system can win from your efforts. </para> + + <para> Support the idea of free software! </para> + </sect1> +</chapter> diff --git a/doc/guide/files/ftp-layout.xml b/doc/guide/files/ftp-layout.xml new file mode 100644 index 00000000000..f75911310fc --- /dev/null +++ b/doc/guide/files/ftp-layout.xml @@ -0,0 +1,94 @@ +<!-- $NetBSD: ftp-layout.xml,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ --> + +<appendix id="ftp-layout"> + <title>Layout of the FTP server's package archive</title> + + <para>Layout for precompiled binary packages on ftp.NetBSD.org:</para> + + <!-- BEWARE! Use no tabs here, only spaces! --> + <programlisting> +/pub/NetBSD/packages/ + distfiles/ + + # Unpacked pkgsrc trees + pkgsrc-current -> /pub/NetBSD/NetBSD-current/pkgsrc + pkgsrc-2003Q4 -> N/A + pkgsrc-2004Q1/pkgsrc + + # pkgsrc archives + pkgsrc-current.tar.gz -> ../NetBSD-current/tar_files/pkgsrc.tar.gz + pkgsrc-2003Q4.tar.gz -> N/A + pkgsrc-2004Q1.tar.gz -> N/A + + # Per pkgsrc-release/OS-release/arch package archives + pkgsrc-2003Q4/ + NetBSD-1.6.2/ + i386/ + All/ + archivers/ + foo -> ../All/foo + ... + pkgsrc-2004Q1/ + NetBSD-1.6.2/ + i386/ + All/ + ... + NetBSD-2.0/ + i386/ + All/ + ... + SunOS-5.9/ + sparc/ + All/ + ... + x86/ + All/ + ... + + # Per os-release package archive convenience links + NetBSD-1.6.2 -> 1.6.2 + 1.6.2/ + i386 -> ../pkgsrc-2004Q1/NetBSD-1.6.2/i386 + m68k/ + All/ + archivers/ + foo -> ../All/foo + ... + amiga -> m68k + atari -> m68k + ... + + 2.0 -> NetBSD-2.0 # backward compat, historic + NetBSD-2.0/ + i386 -> ../pkgsrc-2004Q1/NetBSD-2.0/i386 + SunOS-5.9/ + sparc -> ../pkgsrc-2004Q1/SunOS-5.9/sparc + x86 -> ../pkgsrc-2004Q1/SunOS-5.9/x86 + </programlisting> + + <para> + To create:</para> + + <orderedlist> + <listitem> + <para> Run bulk build, see <xref linkend="bulkbuild"/> </para> + </listitem> + + <listitem> + <para> Upload /usr/pkgsrc/packages to </para> + + <programlisting> ftp://ftp.NetBSD.org/pub/NetBSD/packages/\ + pkgsrc-2004Q3/\ # pkgsrc-branch + `uname -s`-`uname -r`/ # OS & version + `uname -p` # architecture + </programlisting> + + </listitem> + + <listitem> + <para> If necessary, create a symlink <command>ln -s `uname -m` `uname + -p`</command> (amiga -> m68k, ...) </para> + </listitem> + </orderedlist> + +</appendix> diff --git a/doc/guide/files/getting.xml b/doc/guide/files/getting.xml new file mode 100644 index 00000000000..4a9ae02b75c --- /dev/null +++ b/doc/guide/files/getting.xml @@ -0,0 +1,59 @@ +<!-- $NetBSD: getting.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="getting"> + <title>Where to get pkgsrc</title> + + <para>There are three ways to get pkgsrc. Either as a tar file, via SUP, or + via CVS. All three ways are described here.</para> + + <sect1> + <title>As tar file</title> + + <para>To get pkgsrc going, you need to get the pkgsrc.tar.gz file + from <ulink + url="ftp://ftp.NetBSD.org/pub/NetBSD-current/tar_files/pkgsrc.tar.gz">ftp.NetBSD.org</ulink> + and unpack it into <filename>/usr/pkgsrc</filename>.</para> + + </sect1> + + <sect1> + <title>Via SUP</title> + + <para>As an alternative to the tar file, you can get pkgsrc via + the Software Update Protocol, SUP. To do so, make sure your + supfile has a line</para> + + <programlisting>release=pkgsrc</programlisting> + + <para>in it, see the examples in + <filename>/usr/share/examples/supfiles</filename>, and that the + <filename>/usr/pkgsrc</filename> directory exists. Then, simply run + <command>sup -v <replaceable>/path/to/your/supfile</replaceable></command>.</para> + </sect1> + + <sect1> + <title>Via CVS</title> + + <para>To get pkgsrc via CVS, make sure you have <quote>cvs</quote> installed. If not present on + your system, it can be found as precompiled binary on ftp.NetBSD.org. + To do an initial (full) checkout of pkgsrc, do the following steps:</para> + + <screen>&cprompt; <userinput>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</userinput> +&cprompt; <userinput>setenv CVS_RSH ssh</userinput> +&cprompt; <userinput>cd /usr</userinput> +&cprompt; <userinput>cvs checkout -P pkgsrc</userinput></screen> + + <para>This will create the <filename>pkgsrc</filename> directory in your + <filename>/usr</filename>, and all the package source will be stored + under <filename>/usr/pkgsrc</filename>. To update pkgsrc + after the initial checkout, make sure you have + <varname>CVS_RSH</varname> set as above, then do:</para> + + <screen>&cprompt; <userinput>cd /usr/pkgsrc</userinput> +&cprompt; <userinput>cvs -q update -dP</userinput></screen> + + <para>Please also note that it is possible to have multiple copies of the + pkgsrc hierarchy in use at any one time - all work is done relatively + within the pkgsrc tree.</para> + </sect1> +</chapter> diff --git a/doc/guide/files/introduction.xml b/doc/guide/files/introduction.xml new file mode 100644 index 00000000000..787a15fdcf1 --- /dev/null +++ b/doc/guide/files/introduction.xml @@ -0,0 +1,227 @@ +<!-- $NetBSD: introduction.xml,v 1.1.1.1 2004/10/21 14:27:38 grant 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.FreeBSD.org/">FreeBSD</ulink></para> + </listitem> + + <listitem> + <para><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> diff --git a/doc/guide/files/logs.xml b/doc/guide/files/logs.xml new file mode 100644 index 00000000000..e2302b65642 --- /dev/null +++ b/doc/guide/files/logs.xml @@ -0,0 +1,111 @@ +<!-- $NetBSD: logs.xml,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ --> + +<appendix id="logs"> + <title>Build logs</title> + + <sect1 id="logs.building"> + <title>Building figlet</title> + + <screen>&rprompt; <userinput>make</userinput> +===> Checking for vulnerabilities in figlet-2.2.1nb2 +=> figlet221.tar.gz doesn't seem to exist on this system. +=> Attempting to fetch figlet221.tar.gz from ftp://ftp.figlet.org/pub/figlet/program/unix/. +=> [172219 bytes] +Connected to ftp.plig.net. +220 ftp.plig.org NcFTPd Server (licensed copy) ready. +331 Guest login ok, send your complete e-mail address as password. +230-You are user #5 of 500 simultaneous users allowed. +230- +230- ___ _ _ _ +230- | _| |_ ___ ___| |_|___ ___ ___ ___ +230- | _| _| . |_| . | | | . |_| . | _| . | +230- |_| |_| | _|_| _|_|_|_ |_|___|_| |_ | +230- |_| |_| |___| |___| +230- +230-** Welcome to ftp.plig.org ** +230- +230-Please note that all transfers from this FTP site are logged. If you +230-do not like this, please disconnect now. +230- +230-This arhive is available via +230- +230-HTTP: http://ftp.plig.org/ +230-FTP: ftp://ftp.plig.org/ (max 500 connections) +230-RSYNC: rsync://ftp.plig.org/ (max 30 connections) +230- +230-Please email comments, bug reports and requests for packages to be +230-mirrored to ftp-admin@plig.org. +230- +230- +230 Logged in anonymously. +Remote system type is UNIX. +Using binary mode to transfer files. +200 Type okay. +250 "/pub" is new cwd. +250-"/pub/figlet" is new cwd. +250- +250-Welcome to the figlet archive at ftp.figlet.org +250- +250- ftp://ftp.figlet.org/pub/figlet/ +250- +250-The official FIGlet web page is: +250- http://www.figlet.org/ +250- +250-If you have questions, please mailto:info@figlet.org. If you want to +250-contribute a font or something else, you can email us. +250 +250 "/pub/figlet/program" is new cwd. +250 "/pub/figlet/program/unix" is new cwd. +local: figlet221.tar.gz remote: figlet221.tar.gz +502 Unimplemented command. +227 Entering Passive Mode (195,40,6,41,246,104) +150 Data connection accepted from 84.128.86.72:65131; transfer starting for figlet221.tar.gz (172219 bytes). +38% |************** | 65800 64.16 KB/s 00:01 ETA +226 Transfer completed. +172219 bytes received in 00:02 (75.99 KB/s) +221 Goodbye. +=> Checksum OK for figlet221.tar.gz. +===> Extracting for figlet-2.2.1nb2 +===> Required installed package ccache-[0-9]*: ccache-2.3nb1 found +===> Patching for figlet-2.2.1nb2 +===> Applying pkgsrc patches for figlet-2.2.1nb2 +===> Overriding tools for figlet-2.2.1nb2 +===> Creating toolchain wrappers for figlet-2.2.1nb2 +===> Configuring for figlet-2.2.1nb2 +===> Building for figlet-2.2.1nb2 +gcc -O2 -DDEFAULTFONTDIR=\"/usr/pkg/share/figlet\" -DDEFAULTFONTFILE=\"standard.flf\" figlet.c zipio.c crc.c inflate.c -o figlet +chmod a+x figlet +gcc -O2 -o chkfont chkfont.c +=> Unwrapping files-to-be-installed. +&rprompt; +&rprompt; <userinput>make install</userinput> +===> Checking for vulnerabilities in figlet-2.2.1nb2 +===> Installing for figlet-2.2.1nb2 +install -d -o root -g wheel -m 755 /usr/pkg/bin +install -d -o root -g wheel -m 755 /usr/pkg/man/man6 +mkdir -p /usr/pkg/share/figlet +cp figlet /usr/pkg/bin +cp chkfont /usr/pkg/bin +chmod 555 figlist showfigfonts +cp figlist /usr/pkg/bin +cp showfigfonts /usr/pkg/bin +cp fonts/*.flf /usr/pkg/share/figlet +cp fonts/*.flc /usr/pkg/share/figlet +cp figlet.6 /usr/pkg/man/man6 +===> Registering installation for figlet-2.2.1nb2 +&rprompt;</screen> + </sect1> + + <sect1 id="logs.package"> + <title>Packaging figlet</title> + + <screen>&rprompt; <userinput>make package</userinput> +===> Checking for vulnerabilities in figlet-2.2.1nb2 +===> Packaging figlet-2.2.1nb2 +===> Building binary package for figlet-2.2.1nb2 +Creating package /home/cvs/pkgsrc/packages/i386/All/figlet-2.2.1nb2.tgz +Using SrcDir value of /usr/pkg +Registering depends:. +&rprompt;</screen> + </sect1> +</appendix> diff --git a/doc/guide/files/options.xml b/doc/guide/files/options.xml new file mode 100644 index 00000000000..002411bd4d9 --- /dev/null +++ b/doc/guide/files/options.xml @@ -0,0 +1,152 @@ +<!-- $NetBSD: options.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="options"> + <title>Options handling</title> + + <para> Many packages have the ability to be built to support + different sets of features. <filename>bsd.options.mk</filename> + is a framework in pkgsrc that provides generic handling of those + options that determine different ways in which the packages can be + built. It's possible for the user to specify exactly which sets + of options will be built into a package or to allow a set of + global default options apply. </para> + + <sect1> + <title>Global default options</title> + + <para> Global default options are listed in + <varname>PKG_DEFAULT_OPTIONS</varname>, which is a list of the + options that should be built into every package if that option + is supported. This variable should be set in + <filename>/etc/mk.conf</filename>. </para> + </sect1> + + <sect1> + <title>Converting packages to use <filename>bsd.options.mk</filename></title> + + <para> The following example shows how + <filename>bsd.options.mk</filename> should be use in a package + <filename>Makefile</filename>, or in a file, + e.g. <filename>options.mk</filename>, that is included by the + main package <filename>Makefile</filename>. + </para> + + <programlisting> +# Global and legacy options +.if defined(WIBBLE_USE_OPENLDAP) && !empty(WIBBLE_USE_OPENLDAP:M[yY][eE][sS]) +PKG_DEFAULT_OPTIONS+= ldap +.endif +.if defined(USE_SASL2) && !empty(USE_SASL2:M[yY][eE][sS]) +PKG_DEFAULT_OPTIONS+= sasl +.endif + +PKG_OPTIONS_VAR= PKG_OPTIONS.wibble +PKG_SUPPORTED_OPTIONS= ldap sasl +# +# Default options for "wibble" package. +# +.if !defined(PKG_OPTIONS.wibble) +PKG_DEFAULT_OPTIONS+= sasl +endif +.include "../../mk/bsd.options.mk" + +# Package-specific option-handling + +### +### LDAP support +### +.if !empty(PKG_OPTIONS:Mldap) +. include "../../databases/openldap/buildlink3.mk" +CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap} +.endif + +### +### SASL authentication +### +.if !empty(PKG_OPTIONS:Msasl) +. include "../../security/cyrus-sasl2/buildlink3.mk" +CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} +.endif + </programlisting> + + <para> The first section only exists if you are converting a + package that had its own ad-hoc options handling to use + <filename>bsd.options.mk</filename>. It converts global or + legacy options variables into an equivalent + <varname>PKG_OPTIONS.<replaceable>pkg</replaceable></varname> + value. These sections will be removed over time as the old + options are in turn deprecated and removed. </para> + + <para> The second section contains the information about which + build options are supported by the package, and any default + options settings if needed. </para> + + <orderedlist> + <listitem> + <para> <varname>PKG_OPTIONS_VAR</varname> is a list of the + name of the &man.make.1; variables that contain the options the + user wishes to select. The recommended value is + <quote>PKG_OPTIONS.<replaceable>pkg</replaceable></quote> + but any package-specific value may be + used. This variable should be set in a package Makefile. + </para> + </listitem> + + <listitem> + <para> <varname>PKG_SUPPORTED_OPTIONS</varname> is a list of + build options supported by the package. This variable + should be set in a package Makefile. </para> + </listitem> + + <listitem> + <para> <varname>${PKG_OPTIONS_VAR}</varname> (the variables + named in <varname>PKG_OPTIONS_VAR</varname>) are variables + that list the selected build options and override any + default options given in + <varname>PKG_DEFAULT_OPTIONS</varname>. If any of the + options begin with a <quote>-</quote>, then that option is + always removed from the selected build options, e.g. + </para> + + <programlisting> + PKG_DEFAULT_OPTIONS= kerberos ldap sasl + PKG_OPTIONS_VAR= WIBBLE_OPTIONS + WIBBLE_OPTIONS= ${PKG_DEFAULT_OPTIONS} -sasl + # implies PKG_OPTIONS == "kerberos ldap" + </programlisting> + + <para>or</para> + + <programlisting> + PKG_OPTIONS_VAR= WIBBLE_OPTIONS + WIBBLE_OPTIONS= kerberos -ldap ldap + # implies PKG_OPTIONS == "kerberos" + </programlisting> + + <para> This variable should be set in + <filename>/etc/mk.conf</filename>. </para> + </listitem> + </orderedlist> + + <para> After the inclusion of bsd.options.mk, the following + variables are set: </para> + + <itemizedlist> + <listitem> + <para> <varname>PKG_OPTIONS</varname> contains the list of + the selected build options, properly filtered to remove + unsupported and duplicate options. + </para> + </listitem> + </itemizedlist> + + <para> The remaining sections contain the logic that is specific + to each option. There should be a check for every option + listed in <varname>PKG_SUPPORTED_OPTIONS</varname>, and there + should be clear documentation on what turning on the option + will do in the comments preceding each section. The correct + way to check for an option is to check whether it is listed in + <varname>PKG_OPTIONS</varname>. + </para> + </sect1> +</chapter> diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml new file mode 100644 index 00000000000..5e2f02a1fb0 --- /dev/null +++ b/doc/guide/files/pkgsrc.xml @@ -0,0 +1,86 @@ +<!-- $NetBSD: pkgsrc.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> +<!-- From: --> +<!-- NetBSD: Packages.txt,v 1.360 2004/09/29 11:33:38 hubertf Exp --> + + +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.2-Based DocBook Extension//EN" [ + +<!ENTITY % man-refs.ent PUBLIC "-//NetBSD//ENTITIES NetBSD Manual Page Entities//EN"> +%man-refs.ent; +<!ENTITY % misc.ent PUBLIC "-//NetBSD//ENTITIES NetBSD Miscellaneous Entities//EN"> +%misc.ent; +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +]> + +<book> + <bookinfo> + <title>The pkgsrc guide</title> + <subtitle>Documentation on the NetBSD package system</subtitle> + + <authorgroup> + <author> + <firstname>Alistair</firstname> + <surname>Crooks</surname> + + <affiliation> + <address><email>agc@NetBSD.org</email></address> + </affiliation> + </author> + + <author> + <firstname>Hubert</firstname> + <surname>Feyrer</surname> + + <affiliation> + <address><email>hubertf@NetBSD.org</email></address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>1994-2004</year> + + <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder> + </copyright> + + <pubdate>$NetBSD: pkgsrc.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $</pubdate> + + <abstract> + <para>Information about using the NetBSD package system (pkgsrc) + from both a user view for installing packages as well as from + a pkgsrc developers' view for creating new packages.</para> + </abstract> + </bookinfo> + + &chap.intro; + + <part id="users-guide"> <?dbhtml filename="users-guide.html"?> + <title id="users-guide.title">pkgsrc user's guide</title> + + &chap.getting; + &chap.platform; + &chap.using; + &chap.binary; + &chap.faq; + </part> + + <!-- "part II" (we need to rid the documentation of this reference) --> + <part id="developers-guide"> <?dbhtml filename="developers-guide.html"?> + <title id="developers-guide.title">pkgsrc developer's guide</title> + + &chap.components; + &chap.plist; + &chap.buildlink; + &chap.options; + &chap.build; + &chap.fixes; + &chap.debug; + &chap.submit; + </part> + + <!-- appendix --> + &chap.examples; + &chap.logs; + &chap.ftp-layout; +</book> diff --git a/doc/guide/files/platforms.xml b/doc/guide/files/platforms.xml new file mode 100644 index 00000000000..cfa366c3f19 --- /dev/null +++ b/doc/guide/files/platforms.xml @@ -0,0 +1,463 @@ +<!-- $NetBSD: platforms.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="platforms"> + <title>Using pkgsrc on systems other than &os;</title> + + <sect1> + <title>Bootstrapping pkgsrc</title> + + <para>For Operating Systems other than &os;, we provide a bootstrap kit to + build the required tools to use pkgsrc on your platform. Besides + support for native &os;, pkgsrc and the bootstrap kit have support for + the following operating systems:</para> + + <itemizedlist> + <listitem> + <para>Darwin (Mac OS X)</para> + </listitem> + + <listitem> + <para>FreeBSD</para> + </listitem> + + <listitem> + <para>Interix (Windows 2000, XP, 2003)</para> + </listitem> + + <listitem> + <para>IRIX</para> + </listitem> + + <listitem> + <para>Linux</para> + </listitem> + + <listitem> + <para>OpenBSD</para> + </listitem> + + <listitem> + <para>Solaris</para> + </listitem> + </itemizedlist> + + <para>Support for other platforms is under development.</para> + + <para>Installing the bootstrap kit should be as simple as:</para> + + <screen> +&rprompt; <userinput>env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc</userinput> +&rprompt; <userinput>cd pkgsrc/bootstrap</userinput> +&rprompt; <userinput>./bootstrap</userinput></screen> + + <para>See <xref linkend="getting"/> for other ways to get + pkgsrc before bootstrapping. The given + <command>bootstrap</command> command will use the defaults of + <filename>/usr/pkg</filename> for the + <emphasis>prefix</emphasis> where programs will be installed in, + and <filename>/var/db/pkg</filename> for the package database + directory where pkgsrc will do it's internal bookkeeping. + However, these can also be set using command-line + parameters.</para> + + <para>Binary packages for the pkgsrc tools and an initial set of packages is + available for supported platforms. An up-to-date list of these can be + found on <ulink url="http://www.pkgsrc.org/">www.pkgsrc.org</ulink>.</para> + </sect1> + + <sect1> + <title>Platform specific notes</title> + + <para>Here are some platform-specific notes you should be aware of.</para> + + <sect2> + <title>Darwin (Mac OS X)</title> + + <para>Darwin 5.x and 6.x are supported. There are two methods of using + pkgsrc on Mac OS X, by using a <link linkend="platform.osx-image">disk + image</link>, or a <link linkend="platform.osx-ufs">UFS + partition</link>.</para> + + <para>Before you start, you will need to download and install the Mac OS X Developer + Tools from Apple's Developer Connection. See <ulink + url="http://developer.apple.com/macosx/">http://developer.apple.com/macosx/</ulink> + for details. Also, make sure you install X11 for Mac OS X and the X11 SDK + from <ulink + url="http://www.apple.com/macosx/x11/download/">http://www.apple.com/macosx/x11/download/</ulink> + if you intend to build packages that use the X11 Window System.</para> + + <para>If you already have a UFS partition, or have a spare partition + that you can format as UFS, it is recommended to use that instead of + the disk image. It'll be somewhat faster and will mount automatically + at boot time, where you must manually mount a disk image.</para> + + <note> + <para>You cannot use a HFS+ file system for pkgsrc, because pkgsrc currently + requires the filesystem to be case-sensitive, and HFS+ is not.</para> + </note> + + <sect3 id="platform.osx-image"> + <title>Using a disk image</title> + + <para>Create the disk image:</para> + + <screen>&rprompt; <userinput>cd pkgsrc/bootstrap</userinput> +&rprompt; <userinput>./ufsdiskimage create ~/Documents/NetBSD 512</userinput> # megabytes - season to taste +&rprompt; <userinput>./ufsdiskimage mount ~/Documents/NetBSD</userinput> +&rprompt; <userinput>sudo chown `id -u`:`id -g` /Volumes/NetBSD</userinput></screen> + + <para>That's it!</para> + </sect3> + + <sect3 id="platform.osx-ufs"> + <title>Using a UFS partition</title> + + <para>By default, <filename>/usr</filename> will be on your root file + system, normally HFS+. It is possible to use the default + <emphasis>prefix</emphasis> of <filename>/usr/pkg</filename> + by symlinking <filename>/usr/pkg</filename> to a directory on a UFS + file system. Obviously, another symlink is required if you want to + place the package database directory outside the + <emphasis>prefix</emphasis>. e.g.</para> + + <screen>&rprompt; <userinput>./bootstrap --pkgdbdir=/usr/pkg/pkgdb --pkgsrcdir=/Volumes/ufs/pkgsrc</userinput></screen> + + <para>If you created your partitions at the time of installing Mac OS X + and formatted the target partition as UFS, it should automatically + mount on <filename>/Volumes/<volume name></filename> when the + machine boots. If you are (re)formatting a partition as UFS, you need + to ensure that the partition map correctly reflects + <quote>Apple_UFS</quote> and not <quote>Apple_HFS</quote>.</para> + + <para>The problem is that none of the disk tools will let you touch a + disk that is booted from. You can unmount the partition, but even if + you newfs it, the partition type will be incorrect and the + automounter won't mount it. It can be mounted manually, but it won't + appear in Finder.</para> + + <para>You'll need to boot off of the OS X Installation (User) CD. When + the Installation program starts, go up to the menu and select Disk + Utility. Now, you will be able to select the partition you want + to be UFS, and Format it Apple UFS. Quit the Disk Utility, quit the + installer which will reboot your machine. The new UFS file system + will appear in Finder.</para> + + <para>Be aware that the permissions on the new file system will be writable + by root only.</para> + + <para>This note is as of 10.2 (Jaguar) and applies to earlier versions. + Hopefully Apple will fix Disk Utility in 10.3 (Panther).</para> + </sect3> + </sect2> + + <sect2> + <title>FreeBSD</title> + + <para> + FreeBSD 4.7 and 5.0 have been tested and are supported, other versions + may work.</para> + + <para>Care should be taken so that the tools that this kit installs do not conflict + with the FreeBSD userland tools. There are several steps:</para> + + <orderedlist> + <listitem> + <para>FreeBSD stores its ports pkg database in + <filename>/var/db/pkg</filename>. It is therefore + recommended that you choose a different location (e.g. + <filename>/usr/pkgdb</filename>) by + using the --pkgdbdir option to the bootstrap script.</para> + </listitem> + + <listitem> + <para>If you do not intend to use the FreeBSD ports tools, it's probably a + good idea to move them out of the way to avoid confusion, e.g.</para> + + <screen>&rprompt; <userinput>cd /usr/sbin</userinput> +&rprompt; <userinput>mv pkg_add pkg_add.orig</userinput> +&rprompt; <userinput>mv pkg_create pkg_create.orig</userinput> +&rprompt; <userinput>mv pkg_delete pkg_delete.orig</userinput> +&rprompt; <userinput>mv pkg_info pkg_info.orig</userinput></screen> +</listitem> + + <listitem> + <para>An example <filename>/etc/mk.conf</filename> file will be placed in + <filename>/etc/mk.conf.example</filename> file + when you use the bootstrap script.</para> + </listitem> + </orderedlist> + </sect2> + + <sect2> + <title>Interix</title> + + <para>Interix is a POSIX compatible subsystem for the Windows NT kernel, + providing a Unix-like environment with a tighter kernel integration than + available with Cygwin. It is part of the Windows Services for Unix + package, available for free for any licensed copy of Windows 2000, XP, + or 2003. SFU can be downloaded from <ulink + url="http://www.microsoft.com/windows/sfu/">http://www.microsoft.com/windows/sfu/</ulink>.</para> + + <para>Services for Unix 3.5, current as of this writing, has been tested. 3.0 + or 3.1 may work, but are not officially supported. (The main difference + in 3.0/3.1 is lack of pthreads.)</para> + + <sect3 id="platform.interix-sfu-install"> + <title>When Installing Interix/SFU</title> + + <para>At an absolute minimum, the following packages must be installed from + the Windows Services for Unix 3.5 distribution in order to use pkgsrc:</para> + + <itemizedlist> + <listitem><para>Utilities -> Base Utilities</para></listitem> + <listitem><para>Interix GNU Components -> (all)</para></listitem> + <listitem><para>Remote Connectivity</para></listitem> + <listitem><para>Interix SDK</para></listitem> + </itemizedlist> + + <para>When using pkgsrc on Interix, DO NOT install the Utilities subcomponent + "UNIX Perl". That is Perl 5.6 without shared module support, installed to + /usr/local, and will only cause confusion. Instead, install Perl 5.8 from + pkgsrc (or from a binary package).</para> + + <para>The Remote Connectivity subcomponent "Windows Remote Shell Service" does + not need to be installed, but Remote Connectivity itself should be + installed in order to have a working inetd.</para> + + <para>Finally, during installation you may be asked whether to enable setuid + behavior for Interix programs, and whether to make pathnames default to + case-sensitive. Setuid should be enabled, and case-sensitivity MUST be + enabled. (Without case-sensitivity, a large number of packages including + perl will not build.)</para> + + </sect3> + + <sect3 id="platform.interix-sfu-postinstall"> + <title>What to do if Interix/SFU is already installed</title> + + <para>If SFU is already installed and you wish to alter these settings to work + with pkgsrc, note the following things.</para> + + <itemizedlist> + <listitem> + <para>To uninstall UNIX Perl, use Add/Remove Programs, select Microsoft + Windows Services for UNIX, then click Change. In the installer, choose + Add or Remove, then uncheck Utilities->UNIX Perl.</para> + </listitem> + <listitem> + <para>To enable case-sensitivity for the filesystem, run REGEDIT.EXE, and + change the following registry key:</para> + <para>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel</para> + <para>Set the DWORD value "obcaseinsensitive" to 0; then reboot.</para> + </listitem> + <listitem> + <para>To enable setuid binaries (optional), run REGEDIT.EXE, and change the + following registry key:</para> + <para>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Services for UNIX</para> + <para>Set the DWORD value "EnableSetuidBinaries" to 1; then reboot.</para> + </listitem> + </itemizedlist> + + </sect3> + <sect3 id="platform.interix-notes"> + <title>Important notes for using pkgsrc</title> + + <para>The package imanager (either the pkgsrc "su" user, or the user + running "pkg_add") must be a member of the local Administrators + group. Such a user must also be used to run the bootstrap. This is + slightly relaxed from the normal pkgsrc requirement of "root".</para> + + <para>The package manager should use a umask of 002. "make install" will + automatically complain if this is not the case. This ensures that + directories written in /var/db/pkg are Administrators-group writeable.</para> + + <para>The popular Interix binary packages from http://www.interopsystems.com/ + use an older version of pkgsrc's pkg_* tools. Ideally, these should + NOT be used in conjunction with pkgsrc. If you choose to use them at + the same time as the pkgsrc packages, ensure that you use the proper + pkg_* tools for each type of binary package.</para> + + </sect3> + </sect2> + + <sect2> + <title>IRIX</title> + + <para>You will need a working C compiler, either gcc or SGI's MIPS and MIPSpro + compiler (cc/c89). Please set the <varname>CC</varname> environment variable + according to your preference. If you do not have a license for the MIPSpro + compiler suite, you can download a gcc tardist file from <ulink + url="http://freeware.sgi.com/">http://freeware.sgi.com/</ulink>.</para> + + <para>Please note that you will need IRIX 6.5.17 or higher, as this is the earliest + version of IRIX providing support for if_indextoname(3), if_nametoindex(3), + etc.</para> + + <para>At this point in time, pkgsrc only supports one ABI. That is, you can not + switch between the old 32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If + you start out using "abi=n32", that's what all your packages will be built + with.</para> + + <para>Therefore, please make sure that you have no conflicting + <varname>CFLAGS</varname> in your environment or the + <filename>/etc/mk.conf</filename>. Particularly, make sure that you do not + try to link n32 object files with lib64 or vice versa. Check your + <filename>/etc/compiler.defaults</filename>!</para> + + <para>If you have the actual pkgsrc tree mounted via NFS from a different host, + please make sure to set <varname>WRKOBJDIR</varname> to a local directory, + as it appears that IRIX linker occasionally runs into issues when trying to + link over a network mounted filesystem.</para> + + <para>The bootstrapping process should set all the right options for programs such + as imake(1), but you may want to set some options depending on your local + setup. Please see <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename> and, of + course, your compilers man pages for details.</para> + </sect2> + +<!-- +<sect2> +<title>Linux</title> +<para> +... XXX +</para> +</sect2> +--> + + <sect2> + <title>OpenBSD</title> + + <para>OpenBSD 3.0 and 3.2 are tested and supported.</para> + + <para>Care should be taken so that the tools that this kit installs do not conflict + with the OpenBSD userland tools. There are several steps:</para> + + <orderedlist> + <listitem> + <para>OpenBSD stores its ports pkg database in + <filename>/var/db/pkg</filename>. It is therefore + recommended that you choose a different location (e.g. + <filename>/usr/pkgdb</filename>) by + using the --pkgdbdir option to the bootstrap script.</para> + </listitem> + + <listitem> + <para>If you do not intend to use the OpenBSD ports tools, it's probably a + good idea to move them out of the way to avoid confusion, e.g.</para> + + <screen>&rprompt; <userinput>cd /usr/sbin</userinput> +&rprompt; <userinput>mv pkg_add pkg_add.orig</userinput> +&rprompt; <userinput>mv pkg_create pkg_create.orig</userinput> +&rprompt; <userinput>mv pkg_delete pkg_delete.orig</userinput> +&rprompt; <userinput>mv pkg_info pkg_info.orig</userinput></screen> + </listitem> + + <listitem> + <para>An example <filename>/etc/mk.conf</filename> file will be placed in + <filename>/etc/mk.conf.example</filename> file + when you use the bootstrap script. OpenBSD's make program uses + <filename>/etc/mk.conf</filename> + as well. You can work around this by enclosing all the pkgsrc specific parts + of the file with:</para> + + <programlisting>.ifdef BSD_PKG_MK +# pkgsrc stuff, e.g. insert bsd.pkg.defaults.mk or similar here +.else +# OpenBSD stuff +.endif</programlisting> + </listitem> + </orderedlist> + </sect2> + + <sect2> + <title>Solaris</title> + + <para>Solaris 2.6 through 9 are supported on both x86 and sparc. You will need a working C + compiler. Both gcc 2.95.3 and Sun WorkShop 5 have been tested.</para> + + <para>The following packages are required on Solaris 8 for the bootstrap + process and to build packages.</para> + + <itemizedlist> + <listitem> + <para>SUNWsprot</para> + </listitem> + + <listitem> + <para>SUNWarc</para> + </listitem> + + <listitem> + <para>SUNWbtool</para> + </listitem> + + <listitem> + <para>SUNWtoo</para> + </listitem> + + <listitem> + <para>SUNWlibm</para> + </listitem> + </itemizedlist> + + <para>Please note the use of GNU binutils on Solaris is + <emphasis>not</emphasis> supported.</para> + + <sect3> + <title>If you are using gcc</title> + + <para>It makes life much simpler if you only use the same gcc consistently + for building all packages.</para> + + <para>It is recommended that an external gcc be used only for bootstrapping, + then either build gcc from <pkg>lang/gcc</pkg> or install a binary gcc + package, then remove gcc used during bootstrapping.</para> + + <para>Binary packages of gcc can be found through <ulink + url="http://www.sun.com/bigadmin/common/freewareSearch.html">http://www.sun.com/bigadmin/common/freewareSearch.html</ulink>.</para> + </sect3> + + <sect3> + <title>If you are using Sun WorkShop</title> + + <para>You will need at least the following packages installed (from WorkShop + 5.0)</para> + + <itemizedlist> + <listitem> + <para>SPROcc - Sun WorkShop Compiler C 5.0</para> + </listitem> + + <listitem> + <para>SPROcpl - Sun WorkShop Compiler C++ 5.0</para> + </listitem> + + <listitem> + <para>SPROild - Sun WorkShop Incremental Linker</para> + </listitem> + + <listitem> + <para>SPROlang - Sun WorkShop Compilers common components</para> + </listitem> + </itemizedlist> + + <para>You should set <varname>CC</varname>, <varname>CXX</varname> and + optionally, <varname>CPP</varname> in <filename>/etc/mk.conf</filename>, + eg.</para> + + <programlisting>CC= cc +CXX= CC +CPP= /usr/ccs/lib/cpp</programlisting> + + <para>You may also want to build 64-bit binaries, eg.</para> + + <programlisting>CFLAGS= -xtarget=ultra -xarch=v9</programlisting> + + <para>Whichever compiler you use, please ensure the compiler tools and + your $prefix are in your <varname>PATH</varname>. This includes + <filename>/usr/ccs/{bin,lib}</filename> + and eg. <filename>/usr/pkg/{bin,sbin}</filename>.</para> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/doc/guide/files/plist.xml b/doc/guide/files/plist.xml new file mode 100644 index 00000000000..8d888df1ad4 --- /dev/null +++ b/doc/guide/files/plist.xml @@ -0,0 +1,293 @@ +<!-- $NetBSD: plist.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="plist"> + <title>PLIST issues</title> + + <para> The <filename>PLIST</filename> file contains a package's + <quote>packing list</quote>, i.e. a list of files that belong to + the package (relative to the <filename>${PREFIX}</filename> + directory it's been installed in) plus some additional statements + - see the &man.pkg.create.1; manpage for a full list. + This chapter addresses some issues that need attention when + dealing with the <filename>PLIST</filename> file (or files, see + below!).</para> + + + <sect1> + <title>RCS ID</title> + + <para> + Be sure to add a RCS ID line as the first thing in any + <filename>PLIST</filename> file you write: + </para> + + <programlisting>@comment $NetBSD$</programlisting> + </sect1> + + <sect1> + <title>Semi-automatic <filename>PLIST</filename> generation</title> + + <para>You can use the <command>make print-PLIST</command> command + to output a PLIST that matches any new files since the package + was extracted. See <xref linkend="build.helpful-targets"/> for + more information on this target.</para> + </sect1> + + + <sect1 id="print-PLIST"> + <title>Tweaking output of <command>make print-PLIST</command></title> + + <para> If you have used any of the *-dirs packages, as explained in + <xref linkend="faq.common-dirs"/>, you may have noticed that + <command>make print-PLIST</command> outputs a set of + <varname>@comment</varname>s instead of real + <varname>@dirrm</varname> lines. You can also do this for + specific directories and files, so that the results of that + command are very close to reality. This helps <emphasis>a + lot</emphasis> during the update of packages. </para> + + <para> The <varname>PRINT_PLIST_AWK</varname> variable takes a set + of AWK patterns and actions that are used to filter the output of + print-PLIST. You can <emphasis>append</emphasis> any chunk of AWK + scripting you like to it, but be careful with quoting. </para> + + <para> For example, to get all files inside the + <filename>libdata/foo</filename> directory removed from the + resulting PLIST:</para> + + <programlisting> + PRINT_PLIST_AWK+= /^libdata\/foo/ { next; } + </programlisting> + + <para> And to get all the <varname>@dirrm</varname> lines referring + to a specific (shared) directory converted to + <varname>@comment</varname>s: </para> + + <programlisting> + PRINT_PLIST_AWK+= /^@dirrm share\/specific/ { print "@comment " $$0; next; } + </programlisting> + </sect1> + + + <sect1 id="plist.misc"> + <title>Variable substitution in PLIST</title> + + <para> + A number of variables are substituted automatically in PLISTs + when a package is installed on a system. This includes the + following variables: </para> + + <variablelist> + <varlistentry> + <term><varname>${MACHINE_ARCH}</varname>, <varname>${MACHINE_GNU_ARCH}</varname></term> + + <listitem> + <para>Some packages like emacs and perl embed information + about which architecture they were built on into the + pathnames where they install their file. To handle this + case, PLIST will be preprocessed before actually used, and + the symbol + <quote><varname>${MACHINE_ARCH}</varname></quote> will be + replaced by what <command>uname -p</command> gives. The + same is done if the string + <varname>${MACHINE_GNU_ARCH}</varname> is embedded in + PLIST somewhere - use this on packages that have GNU + autoconf created configure scripts.</para> + + <note> + <title>Legacy note</title> + + <para>There used to be a symbol + <quote><varname>$ARCH</varname></quote> that + was replaced by the output of <command>uname + -m</command>, but that's no longer supported and has + been removed.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>${OPSYS}</varname>, <varname>${LOWER_OPSYS}</varname>, <varname>${OS_VERSION}</varname></term> + + <listitem> + <para>Some packages want to embed the OS name and version + into some paths. To do this, use these variables in the + <filename>PLIST</filename>: + </para> + + <itemizedlist> + <listitem> + <para><varname>${OPSYS}</varname> - output of <quote><command>uname -s</command></quote></para> + </listitem> + + <listitem> + <para><varname>${LOWER_OPSYS}</varname> - lowercase common name (eg. <quote>solaris</quote>)</para> + </listitem> + + <listitem> + <para><varname>${OS_VERSION}</varname> - <quote><command>uname -r</command></quote></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>${PKGLOCALEDIR}</varname></term> + + <listitem> + <para>Packages that install locale files should list them in + the PLIST as + <quote>${PKGLOCALEDIR}/locale/de/LC_MESSAGES/...</quote> + instead of <quote>share/locale/de/LC_MESSAGES/...</quote>. + This properly handles the fact that different operating + systems expect locale files to be either in + <filename>share</filename> or <filename>lib</filename> by + default.</para> + </listitem> + </varlistentry> + </variablelist> + + <para> For a complete list of values which are replaced by + default, please look in <filename>bsd.pkg.mk</filename> (and + search for <emphasis>PLIST_SUBST</emphasis>). </para> + + <para> If you want to change other variables not listed above, you + can add variables and their expansions to this variable in the + following way, similar to <varname>MESSAGE_SUBST</varname> (see <xref + linkend="components.optional"/>): </para> + + <programlisting>PLIST_SUBST+= SOMEVAR="somevalue"</programlisting> + + <para>This replaces all occurrences of <quote>${SOMEVAR}</quote> + in the PLIST with <quote>somevalue</quote>. </para> + </sect1> + + <sect1> + <title>Manpage-compression</title> + + <para>Manpages should be installed in compressed form if + <varname>MANZ</varname> is set (in <filename>bsd.own.mk</filename>), + and uncompressed otherwise. To handle this in the + <filename>PLIST</filename> file, the suffix <quote>.gz</quote> is + appended/removed automatically for manpages according to + <varname>MANZ</varname> and <varname>MANCOMPRESSED</varname> being set + or not, see above for details. This modification of the + <filename>PLIST</filename> file is done on a copy of it, not + <filename>PLIST</filename> itself.</para> + </sect1> + + + <sect1> + <title>Changing PLIST source with <varname>PLIST_SRC</varname></title> + + <para>To use one or more files as source for the <filename>PLIST</filename> used + in generating the binary package, set the variable + <varname>PLIST_SRC</varname> to the names of that file(s). + The files are later concatenated using cat(1), and order of things is + important.</para> + </sect1> + + + <sect1> + <title>Platform specific and differing PLISTs</title> + + <para>Some packages decide to install a different set of files based on + the operating system being used. These differences can be + automatically handled by using the following files:</para> + + <itemizedlist> + <listitem> + <para><filename>PLIST.common</filename></para> + </listitem> + + <listitem> + <para><filename>PLIST.${OPSYS}</filename></para> + </listitem> + + <listitem> + <para><filename>PLIST.common_end</filename></para> + </listitem> + </itemizedlist> + + <para>If <filename>PLIST.${OPSYS}</filename> exists, these files are used + instead of <filename>PLIST</filename>. This allows packages which + behave in this way to be handled gracefully. Manually overriding + <varname>PLIST_SRC</varname> for other more exotic uses is also + possible.</para> + </sect1> + + + <sect1 id="faq.common-dirs"> + <title>Sharing directories between packages</title> + + <para> A <quote>shared directory</quote> is a directory where + multiple (and unrelated) packages install files. These + directories are problematic because you have to add special tricks + in the PLIST to conditionally remove them, or have some + centralized package handle them. </para> + + <para> Within pkgsrc, you'll find both approaches. If a directory + is shared by a few unrelated packages, it's often not worth to add + an extra package to remove it. Therefore, one simply does: + </para> + + <programlisting> + @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE} + </programlisting> + + <para> in the PLISTs of all affected packages, instead of the + regular "@dirrm" line. </para> + + <para> However, if the directory is shared across many packages, two + different solutions are available: </para> + + <orderedlist> + <listitem> + <para> If the packages have a common dependency, the directory + can be removed in that. For example, see + <pkg>textproc/scrollkeeper</pkg>, which removes the shared + directory <filename>share/omf</filename>. </para> + </listitem> + + <listitem> + <para> If the packages using the directory are not related at + all (they have no common dependencies), a *-dirs package is + used. </para> + </listitem> + </orderedlist> + + <para> From now on, we'll discuss the second solution. To get an + idea of the *-dirs packages available, issue: </para> + + <programlisting> + &cprompt; cd .../pkgsrc + &cprompt; ls -d */*-dirs + </programlisting> + + <para> Their use from other packages is very simple. The + <varname>USE_DIRS</varname> variable takes a list of package names + (without the <quote>-dirs</quote> part) together with the required + version number (always pick the latest one when writting new + packages). </para> + + <para> For example, if a package installs files under + <filename>share/applications</filename>, it should have the + following line in it: + </para> + + <programlisting> + USE_DIRS+= xdg-1.1 + </programlisting> + + <para> After regenerating the PLIST using <command>make + print-PLIST</command>, you should get the right (commented out) + lines. </para> + + <para> Note that, even if your package is using + <filename>$X11BASE</filename>, it must not depend on the + *-x11-dirs packages. Just specify the name without that part and + pkgsrc (in particular, <filename>mk/dirs.mk</filename>) will take + care of it. </para> + </sect1> + +</chapter> diff --git a/doc/guide/files/share/catalog b/doc/guide/files/share/catalog new file mode 100644 index 00000000000..c5adaebecd1 --- /dev/null +++ b/doc/guide/files/share/catalog @@ -0,0 +1,4 @@ +-- $NetBSD: catalog,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ -- + +PUBLIC "-//NetBSD//DOCUMENT DocBook DSSSL Stylesheet//EN" + "netbsd.dsl" diff --git a/doc/guide/files/share/default-html-chunk.xsl b/doc/guide/files/share/default-html-chunk.xsl new file mode 100644 index 00000000000..6f677d6f405 --- /dev/null +++ b/doc/guide/files/share/default-html-chunk.xsl @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding="iso-8859-1"?> + +<!-- $NetBSD: default-html-chunk.xsl,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ --> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0' + xmlns="http://www.w3.org/TR/xhtml1/transitional" + exclude-result-prefixes="#default"> + + <xsl:import href="../master-chunk.xsl"/> +</xsl:stylesheet> diff --git a/doc/guide/files/share/default-html.xsl b/doc/guide/files/share/default-html.xsl new file mode 100644 index 00000000000..a2e5f53cf7b --- /dev/null +++ b/doc/guide/files/share/default-html.xsl @@ -0,0 +1,11 @@ +<?xml version='1.0'?> + +<!-- $NetBSD: default-html.xsl,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ --> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0' + xmlns="http://www.w3.org/TR/xhtml1/transitional" + exclude-result-prefixes="#default"> + + <xsl:import href="../master.xsl"/> +</xsl:stylesheet> diff --git a/doc/guide/files/share/default.dsl b/doc/guide/files/share/default.dsl new file mode 100644 index 00000000000..cac7e359efa --- /dev/null +++ b/doc/guide/files/share/default.dsl @@ -0,0 +1,15 @@ +<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ +<!ENTITY netbsd.dsl PUBLIC "-//NetBSD//DOCUMENT DocBook DSSSL Stylesheet//EN" CDATA DSSSL> +]> + +<!-- $NetBSD: default.dsl,v 1.1.1.1 2004/10/21 14:27:43 grant Exp $ --> + +<style-sheet> + <style-specification use="docbook"> + <style-specification-body> + + </style-specification-body> + </style-specification> + + <external-specification id="docbook" document="netbsd.dsl"> +</style-sheet> diff --git a/doc/guide/files/submit.xml b/doc/guide/files/submit.xml new file mode 100644 index 00000000000..dbb4b20f76f --- /dev/null +++ b/doc/guide/files/submit.xml @@ -0,0 +1,193 @@ +<!-- $NetBSD: submit.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ --> + +<chapter id="submit"> <?dbhtml filename="submit.html"?> +<title>Submitting and Committing</title> + +<sect1> +<title>Submitting your packages</title> +<para> +You have to separate between binary and <quote>normal</quote> (source) +packages here: +</para> + +<itemizedlist> +<listitem> +<para>precompiled binary packages</para> +<para> + Our policy is that we accept binaries only from pkgsrc developers to + guarantee that the packages don't contain any trojan horses etc. + This is not to piss anyone off but rather to protect our users! + You're still free to put up your home-made binary packages and tell + the world where to get them. +</para> +</listitem> + +<listitem> +<para>packages</para> +<para> + First, check that your package is complete, compiles and runs well; + see <xref linkend="debug"/> and the rest of this document. Next, + generate an uuencoded gzipped tar(1) archive, preferably with all files + in a single directory. + Finally, <command>send-pr</command> with category <quote>pkg</quote>, a + synopsis which includes the package name and version number, a short + description of your package (contents of the COMMENT variable or DESCR + file are OK) and attach the archive to your PR. +</para> + +<para> + If you want to submit several packages, please send a separate PR for + each one, it's easier for us to track things that way. +</para> + +<para> + Alternatively, you can also import new packages into pkgsrc-wip + (<quote>pkgsrc work-in-progress</quote>); see the homepage at <ulink + url="http://pkgsrc-wip.sourceforge.net/"/> for details. +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1> +<title>Committing: Importing a package into CVS</title> +<para> + This section is only of interest for pkgsrc developers with write + access to the pkgsrc repository. Please remember that cvs + imports files relative to the current working directory, and that + the pathname that you + give the <command>cvs import</command> command is so that it knows where + to place the files in the repository. Newly created packages should be + imported with a vendor tag of <quote>TNF</quote> and a release tag of + <quote>pkgsrc-base</quote>, e.g: +</para> + +<programlisting> + % cd .../pkgsrc/category/pkgname + % cvs import pkgsrc/category/pkgname TNF pkgsrc-base +</programlisting> + +<para> + Remember to move the directory from which you imported out of + the way, or cvs will complain the next time you <quote>cvs + update</quote> your source tree. Also don't forget to add the new + package to the category's <filename>Makefile</filename>. +</para> + +<para> + The commit message of the initial import should include part of the + <filename>DESCR</filename> file, so people reading the mailing lists know + what the package is/does. +</para> + +<para> + Please note all package updates/additions in + <filename>pkgsrc/doc/CHANGES</filename>. It's very + important to keep this file up to date and conforming to the existing + format, because it will be used by scripts to automatically update pages on + <ulink url="http://www.NetBSD.org/">www.NetBSD.org</ulink> and other + sites. Additionally, check the pkgsrc/doc/TODO file and remove the entry + for the package you updated, in case it was mentioned there. +</para> + +<para> + For new packages, <quote>cvs import</quote> is preferred to <quote>cvs + add</quote> because the former gets everything with a single command, + and provides a consistent tag. +</para> +</sect1> + +<sect1> +<title>Updating a Package to a Newer Version</title> +<para> + Please always put a concise, appropriate and relevant summary of the + changes between old and new versions into the commit log when updating + a package. There are various reasons for this: +</para> + +<itemizedlist> +<listitem> +<para> + A URL is volatile, and can change over time. It may go away completely + or its information may be overwritten by newer information. +</para> +</listitem> + +<listitem> +<para> + Having the change information between old and new versions in our CVS + repository is very useful for people who use either cvs or anoncvs. +</para> +</listitem> + +<listitem> +<para> + Having the change information between old and new versions in our CVS + repository is very useful for people who read the pkgsrc-changes mailing + list, so that they can make tactical decisions about when to upgrade + the package. +</para> +</listitem> +</itemizedlist> + +<para> + Please also recognise that, just because a new version of a package + has been released, it should not automatically be upgraded in the CVS + repository. We prefer to be conservative in the packages that are + included in pkgsrc - development or beta packages are not really the + best thing for most places in which pkgsrc is used. Please use your + judgement about what should go into pkgsrc, and bear in mind that + stability is to be preferred above new and possibly untested features. +</para> +</sect1> + +<sect1> +<title>Moving a Package in pkgsrc</title> + +<orderedlist> +<listitem><para>Make a copy of the directory somewhere else.</para></listitem> + +<listitem><para>Remove all CVS dirs.</para> +<para> + Alternatively to the first two steps you can also do: +</para> +<screen><prompt>%</prompt> <userinput>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</userinput></screen> +<para> + and use that for further work. +</para> +</listitem> + +<listitem><para>Fix <varname>CATEGORIES</varname> and any +<varname>DEPENDS</varname> paths that just did <quote>../package</quote> +instead of <quote>../../category/package</quote>.</para> +</listitem> + +<listitem><para><command>cvs import</command> the modified package in the new +place.</para></listitem> + +<listitem><para>Check if any package depends on it: +<screen><prompt>%</prompt> <userinput>cd /usr/pkgsrc</userinput> +<prompt>%</prompt> <userinput>grep /package */*/Makefile* */*/buildlink*</userinput></screen> +</para> +</listitem> + +<listitem><para>Fix paths in packages from step 5 to point to new location.</para></listitem> + +<listitem><para><command>cvs rm (-f)</command> the package at the old location.</para></listitem> + +<listitem><para>Remove from <filename>oldcategory/Makefile</filename>.</para></listitem> + +<listitem><para>Add to <filename>newcategory/Makefile</filename>.</para></listitem> + +<listitem><para>Commit the changed and removed files:</para> +<screen><prompt>%</prompt> <userinput>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</userinput></screen> +<para> + (and any packages from step 5, of course). +</para> +</listitem> +</orderedlist> + +</sect1> + +</chapter> diff --git a/doc/guide/files/using.xml b/doc/guide/files/using.xml new file mode 100644 index 00000000000..c97cc148515 --- /dev/null +++ b/doc/guide/files/using.xml @@ -0,0 +1,286 @@ +<!-- $NetBSD: using.xml,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $ --> + +<chapter id="using"> <?dbhtml filename="using.html"?> + <title>Using pkgsrc</title> + + <sect1 id="getting-started"> + <title>Working with binary packages</title> + + <para> This section describes how to find, retrieve and install a + precompiled binary package that someone else already prepared + for your type of machine. </para> + + <sect2> + <title>Where to get binary packages</title> + + <para> Precompiled packages are stored on ftp.NetBSD.org and its + mirrors in the directory + <filename>/pub/NetBSD/packages</filename> for anonymous FTP + access. Please pick the right subdirectory there as indicated + by <command>uname -p</command>. In that directory, there is a + subdirectory for each category plus a subdirectory + <filename>All</filename> which includes the actual binaries in + <filename>.tgz</filename> files. The category subdirectories + use symbolic links to those files (this is the same directory + layout as in + <filename>/usr/pkgsrc/packages</filename>). </para> + + <para> This same directory layout applies for CDROM + distributions, only that the directory may be rooted somewhere + else, probably somewhere below + <filename>/cdrom</filename>. Please consult your CDROMs + documentation for the exact location. </para> + </sect2> + + <sect2> + <title>How to use binary packages</title> + + <para> If you have the files on a CDROM or downloaded them to + your hard disk, youcan install them with the following command + (be sure to<command>su</command> to root first):</para> + + <screen><prompt>#</prompt> <userinput>pkg_add /path/to/package.tgz</userinput></screen> + + <para> If you have FTP access and you don't want to download the + packages via FTP prior to installation, you can do this + automatically by giving <command>pkg_add</command> an FTP URL: + </para> + + <screen><prompt>#</prompt> <userinput>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSvers>/<arch>/All/package.tgz</userinput></screen> + + <para>If there is any doubt, the uname utility can be used to + determine the <OSvers>, and <arch> by running + <command>uname -rp</command>. </para> + + <para>Also note that any prerequisite packages needed to run the + package in question will be installed, too, assuming they are + present where you install from. </para> + + <para>After you've installed packages, be sure to have + <filename>/usr/pkg/bin</filename> in your + <varname>PATH</varname> so you can actually start the just + installed program. </para> + </sect2> + + <sect2> + <title>A word of warning</title> + + <para> Please pay very careful attention to the warnings + expressed in the &man.pkg.add.1; manual page about the + inherent dangers of installing binary packages which you did + not create yourself, and the security holes that can be + introduced onto your system by indiscriminate adding of such + files. </para> + </sect2> + </sect1> + + <sect1> + <title>Building packages from source</title> + + <para> This assumes that the package is already in pkgsrc. If it + is not, see <xref linkend="developers-guide"/>. </para> + + <sect2> + <title>Requirements</title> + + <para> To build packages from source on a NetBSD system the + <quote>comp</quote> and the <quote>text</quote> distribution + sets must be installed. If you want to build X11 related + packages the <quote>xbase</quote> and <quote>xcomp</quote> + distribution sets are required, too.</para> + </sect2> + + + <sect2> + <title>Fetching distfiles</title> + + <para>The distfile (i.e. the unmodified source) + must exist on your system for the packages system to be able + to build it. If it does not exist, pkgsrc will use &man.ftp.1; to + fetch it automatically.</para> + + <para>You can overwrite some of the major distribution sites to fit to sites + that are close to your own. Have a look at + <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename> to find some examples + - in particular, look for the <varname>MASTER_SORT</varname>, + <varname>MASTER_SORT_REGEX</varname> and + <varname>INET_COUNTRY</varname> definitions. This may save some of your + bandwidth and time.</para> + + <para>You can change these settings either in your shell's environment, or, + if you want to keep the settings, by editing the + <filename>/etc/mk.conf</filename> file, + and adding the definitions there.</para> + + <para>If you don't have a permanent Internet connection and you want to know + which files to download, <command>make fetch-list</command> will tell you + what you'll need. Put these distfiles into + <filename>/usr/pkgsrc/distfiles</filename>.</para> + </sect2> + + <sect2> + <title>How to build and install</title> + + <para>Assuming that the distfile has been fetched (see previous section), become + root and change into the relevant directory and running + <command>make</command>. For example, type </para> + + <screen>&cprompt; <userinput>cd misc/figlet</userinput> +&cprompt; <userinput>make</userinput></screen> + + <para>at the shell prompt to build the various components of the + package, and</para> + + <screen>&rprompt; <userinput>make install</userinput></screen> + + <para>to install the various components into the correct places + on your system. Installing the package on your system requires + you to be root. However, pkgsrc has a + <emphasis>just-in-time-su</emphasis> feature, which allows you + to only become root for the actual installation step</para> + + <para>Taking the figlet utility as an example, we can install it on our + system by building as shown in <xref linkend="logs"/>.</para> + + <para>The program is installed under the default root of the packages tree - + <filename>/usr/pkg</filename>. Should this not conform to your tastes, + set the <varname>LOCALBASE</varname> + variable in your environment, and it will use that value as the root of + your packages tree. So, to use <filename>/usr/local</filename>, set + <varname>LOCALBASE=/usr/local</varname> in your environment. Please note + that you should use a directory which is + dedicated to packages and not shared with other programs (ie, do not try + and use <varname>LOCALBASE=/usr</varname>). Also, you should not try to + add any of your own files or directories (such as <filename>src/</filename>, + <filename>obj/</filename>, or <filename>pkgsrc/</filename>) below the + <varname>LOCALBASE</varname> tree. This is to prevent possible conflicts + between programs and other files installed by the package system and + whatever else may have been installed there.</para> + + <para>Some packages look in <filename>/etc/mk.conf</filename> to alter some + configuration options at build time. Have a look at + <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename> to + get an overview of what will be set there by default. Environment + variables such as <varname>LOCALBASE</varname> + can be set in <filename>/etc/mk.conf</filename> to + save having to remember to set them each time you want to use pkgsrc.</para> + + <para>Occasionally, people want to <quote>look under the covers</quote> to see + what is going on when a package is building or being installed. This may be + for debugging purposes, or out of simple curiosity. A number of utility + values have been added to help with this.</para> + + <orderedlist> + <listitem> + <para>If you invoke the &man.make.1; command with <varname>PKG_DEBUG_LEVEL=2</varname>, + then a huge amount of information will be displayed. For example,</para> + + <screen><userinput>make patch PKG_DEBUG_LEVEL=2</userinput></screen> + + <para>will show all the commands that are invoked, up to and including the + <quote>patch</quote> stage.</para> + </listitem> + + <listitem> + <para>If you want to know the value of a certain make(1) definition, then + the <varname>VARNAME</varname> definition should be used, in conjunction + with the show-var target. e.g. to show the expansion of the &man.make.1; variable + <varname>DISTFILES</varname>:</para> + + <screen>&cprompt; <userinput>make show-var VARNAME=LOCALBASE</userinput> +/usr/pkg +&cprompt; + </screen> + + </listitem> + </orderedlist> + + <para>If you want to install a binary package that you've either + created yourself (see next section), that you put into pkgsrc/packages manually or + that is located on a remote FTP server, you can use the the "bin-install" + target. This target will install a binary package - if available - via + &man.pkg.add.1;, else do a <command>make package</command>. + The list of remote + FTP sites searched is kept in the variable + <varname>BINPKG_SITE</varname>, which defaults to + ftp.NetBSD.org. Any flags that should be added to &man.pkg.add.1; can be put + into <varname>BIN_INSTALL_FLAGS</varname>. + See <filename>pkgsrc/mk/bsd.pkg.defaults.mk</filename> for more details.</para> + + <para>A final word of warning: If you setup a system that has a non-standard + setting for <varname>LOCALBASE</varname>, be sure to set that + before any packages are installed, as you can not use several directories + for the same purpose. Doing so will result in pkgsrc not being able to + properly detect your installed packages, and fail miserably. Note also that + precompiled binary packages are usually built with the default + <varname>LOCALBASE</varname> of + <filename>/usr/pkg</filename>, and that you should <emphasis>not</emphasis> + install any if you use a non-standard <varname>LOCALBASE</varname>.</para> + </sect2> + + <sect2> + <title>Selecting the compiler</title> + + <para>By default, pkgsrc will use GCC to build packages. This may be + overridden by setting the following variables in /etc/mk.conf: + </para> + + <variablelist> + <varlistentry> + <term><varname>PKGSRC_COMPILER</varname>:</term> + + <listitem> + <para> This is a list of values specifying the chain of + compilers to invoke when building packages. Valid values + are: </para> + + <itemizedlist> + <listitem><para><varname>distcc</varname>: + distributed C/C++ (chainable)</para> + </listitem> + + <listitem><para><varname>ccache</varname>: + compiler cache (chainable)</para> + </listitem> + + <listitem><para><varname>gcc</varname>: + GNU C/C++ Compiler</para> + </listitem> + + <listitem><para><varname>mipspro</varname>: + Silicon Graphics, Inc. MIPSpro (n32/n64)</para> + </listitem> + + <listitem><para><varname>mipspro</varname>: + Silicon Graphics, Inc. MIPSpro (o32)</para> + </listitem> + + <listitem><para><varname>sunpro</varname>: + Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para> + </listitem> + </itemizedlist> + + <para> The default is + <quote><varname>gcc</varname></quote>. You can use + <varname>ccache</varname> and/or + <varname>distcc</varname> with an appropriate + <varname>PKGSRC_COMPILER</varname> setting, + e.g. <quote><varname>ccache gcc</varname></quote>. This + variable should always be + terminated with a value for a real compiler. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>GCC_REQD</varname>:</term> + <listitem> + <para> This specifies the minimum version of GCC to use + when building packages. If the system GCC doesn't + satisfy this requirement, then pkgsrc will build and + install one of the GCC packages to use instead. </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> +</chapter> |