Annotation of htdocs/developers/pkgsrc/index.xml, revision 1.2

1.1       jschauma    1: <?xml version="1.0"?>
                      2: <!DOCTYPE webpage
                      3:   PUBLIC "-//Norman Walsh//DTD Website V2.2//EN"
                      4:     "http://docbook.sourceforge.net/release/website/2.2/website.dtd" [
                      5: 
                      6: <!ENTITY % man-refs.ent SYSTEM "../../share/xml/man-refs.ent"> %man-refs.ent;
                      7: 
                      8: ]>
                      9: 
                     10: <webpage id="developer-pkgsrc">
                     11: <config param="desc" value="NetBSD pkgsrc Developer Information"/>
1.2     ! wiz        12: <config param="cvstag" value="$NetBSD: index.xml,v 1.1 2004/12/11 19:03:19 jschauma Exp $"/>
        !            13: <config param="rcsdate" value="$Date: 2004/12/11 19:03:19 $"/>
1.1       jschauma   14: <head>
                     15: <!-- Copyright (c) 1994-2004
                     16:         The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
                     17: <title>NetBSD pkgsrc Developer Information</title>
                     18: </head>
                     19: 
                     20: <sect1 role="toc">
                     21: 
                     22: <sect2 id="oberview">
                     23: <title>Overview</title>
                     24: 
                     25: <sect3 id="introduction">
                     26: <title>Introduction</title>
                     27: <para>
                     28:        This page contains pointers to various pkgsrc related material.
                     29:        The information here is likely to be most useful for pkgsrc
                     30:        developers.
                     31: </para>
                     32: </sect3>
                     33: 
                     34: <sect3 id="status">
                     35: <title>Status</title>
                     36: <para>
1.2     ! wiz        37:        <!-- Comment out this paragraph and update it when the next freeze starts. -->
        !            38: <!--
1.1       jschauma   39:        The NetBSD Packages Collection is currently
                     40:        <emphasis role="bold">frozen</emphasis>
                     41:        since <ulink url="../../Changes/##pkgsrc-frozen-q4">2004-12-06</ulink>.
                     42:        This means:
                     43:        <itemizedlist>
                     44:        <listitem>No new packages.</listitem>
                     45:        <listitem>Updates to leaf packages only.</listitem>
                     46:        <listitem>Updates to packages with dependants only when approved in
                     47:                advance.</listitem>
                     48:        <listitem>When in doubt, ask for advice.</listitem>
                     49:        </itemizedlist>
                     50:        The goals for this freeze are:
                     51:        <itemizedlist>
                     52:        <listitem>reducing open <ulink url="../../Gnats/category/pkg.html">pkg PRs</ulink></listitem>
                     53:        <listitem>0 broken packages in i386 bulk builds</listitem>
                     54:        <listitem>the required amount of chocolate submitted as appropriate</listitem>
                     55:        </itemizedlist>
1.2     ! wiz        56: -->
1.1       jschauma   57:        The NetBSD Packages Collection is currently
                     58:        <emphasis role="bold">open</emphasis>.
                     59: </para>
                     60: </sect3>
                     61: </sect2>
                     62: 
                     63: <sect2 id="importing-or-updating">
                     64: <title>Importing or updating packages</title>
                     65: 
                     66: <sect3 id="import">
                     67: <title>How to import a new package</title>
                     68: <para>
                     69: Once you have verified that the package you're about to import is
                     70: correct (pkglint, tested it, etc.), use the following procedure:
                     71: <emphasis role="bold">(Do <emphasis>NOT</emphasis> use a series of "<code>cvs add</code>" commands)</emphasis>
                     72: </para>
                     73: 
                     74: <orderedlist>
                     75: 
1.2     ! wiz        76: <listitem>Please use "<command>pkglint</command>" to test your package before
1.1       jschauma   77:     importing it.  There must not be any fatal error and there should
                     78:     not be any warning.  If you disagree about any of these message
1.2     ! wiz        79:     please contact the <ulink url="mailto:packages@NetBSD.org">pkgsrc developers</ulink>.
        !            80:     </listitem>
1.1       jschauma   81: 
                     82: <listitem>Chapter 10 of the <ulink url="../../Documentation/pkgsrc/">pkgsrc
                     83:     documentation</ulink>
                     84:     describes some debugging techniques.
                     85:     Especially the "make print-PLIST" test should be used to verify the
                     86:     completeness of the package list.</listitem>
                     87: 
1.2     ! wiz        88: <listitem>Use the following command to import the package:
1.1       jschauma   89:     <programlisting>
                     90:     cvs import pkgsrc/category/pkg TNF pkgsrc-base</programlisting>
                     91:     (where the category and pkg name again reflect your package).
                     92: </listitem>
                     93: <listitem>The commit message should include the name, version number of the
                     94:     package and the COMMENT from "Makefile".
                     95: </listitem>
                     96: <listitem>If the new package does not conflict with any existing package,
                     97:     edit pkgsrc/<emphasis>category</emphasis>/Makefile and add it to
                     98:     <code>SUBDIR</code>.
                     99:     Otherwise, add a commented out entry, and add a comment on the same line
                    100:     explaining why it is commented out.
                    101: </listitem>
                    102: <listitem>Update "<filename>pkgsrc/doc/CHANGES</filename>" - note this file
                    103:     is parsed by automatic scripts so keep to the existing format.
                    104:     Times/dates are in UTC.
                    105: </listitem>
                    106: </orderedlist>
                    107: 
                    108: <note><title/>
                    109: <emphasis>NOTE: the pkgsrc/category/pkg path is
                    110: a relative path for the cvsroot, <emphasis role="warning">NOT FOR THE FILES YOU
                    111: ARE IMPORTING. YOU MUST BE IN THE TOP LEVEL DIRECTORY OF YOUR PACKAGE
                    112: WHEN IMPORTING!</emphasis></emphasis>
                    113: </note>
                    114: 
                    115: <note><title/>
                    116: <emphasis>NOTE: "cvs import" is preferred to "cvs add" because the former gets
                    117: everything with a single command, and provides a consistent tag.</emphasis>
                    118: </note>
                    119: </sect3>
                    120: 
                    121: <sect3 id="update">
                    122: <title>Updating a package</title>
                    123: 
                    124: <orderedlist>
                    125: <listitem>Use pkglint and verify the PLIST is correct.</listitem>
                    126: <listitem>If any other package depends upon the one being updated it is
                    127:     important to ensure that their DEPENDS entries are correct,
                    128:     <emphasis role="bold">otherwise they will
                    129:     no longer be able to build</emphasis>. If in doubt run
                    130:     '<code>lintpkgsrc -d</code>'
                    131:     (part of pkglint).</listitem>
                    132: <listitem>Update "pkgsrc/doc/CHANGES" - note this file is parsed by automatic
                    133:     scripts so keep to the existing format. Times/dates are in UTC.</listitem>
                    134: </orderedlist>
                    135: </sect3>
                    136: 
                    137: <sect3 id="pullup">
                    138: <title>Pulling up updates to branches</title>
                    139: 
                    140: <para>
                    141: Critical bug fixes, security updates, and build fixes can be pulled up to the
                    142: latest stable pkgsrc branch. Please forward the 'cvs commit'
                    143: mail from the pkgsrc-changes mailing list to the <ulink
                    144: url="mailto:pullup-pkgsrc@NetBSD.org">pullup</ulink> address.
                    145: </para>
                    146: <para>
                    147: The pkgsrc pullup ticket tracking summaries are found by adding
                    148: "req/index-pkgsrc.html" to the http://releng.NetBSD.org/ URL.
                    149: (Not directly linked to avoid automated e-mail spidering.)
                    150: </para>
                    151: </sect3>
                    152: </sect2>
                    153: 
                    154: <sect2 id="bulk-builds">
                    155: <title>Bulk pkgsrc builds</title>
                    156: 
                    157: <sect3 id="bulkhowto">
                    158: <title>Setting up a bulk pkgsrc build</title>
                    159: <para>
                    160:        Section 4.3 of the <ulink url="../../Documentation/pkgsrc/">pkgsrc
                    161:        documentation</ulink>
                    162:        describes how to set up a bulk pkgsrc build.
                    163: </para>
                    164: </sect3>
                    165: 
                    166: <sect3 id="bulklogs">
                    167: <title>Currently Available Bulk Build Results</title>
                    168: <para>
                    169:        The results of various bulk pkgsrc builds are available online.  
                    170: </para>
                    171: 
                    172: <itemizedlist>
                    173: <listitem><ulink url="http://smaug.fh-regensburg.de/~feyrer/ftp/pub/NetBSD/pkgstat-i386/">http://smaug.fh-regensburg.de/~feyrer/ftp/pub/NetBSD/pkgstat-i386/</ulink>
                    174:   &mdash;i386 logs provided by Hubert Feyrer.  These logs are generated at the
                    175:   end of each run.</listitem>
                    176: <listitem><ulink url="http://www-mtl.mit.edu/~mcmahill/netbsd/pkgstat/">http://www-mtl.mit.edu/~mcmahill/netbsd/pkgstat/</ulink>
                    177:   &mdash;sparc and pmax logs provided by Dan McMahill.  These logs are updated
                    178:   every hour during a build.</listitem>
                    179: <listitem>Results of various bulk builds are posted to the <ulink
                    180:   url="../../MailingLists/#pkgsrc-bulk">pkgsrc-bulk</ulink>
                    181:   mailinglist.</listitem>
                    182: </itemizedlist>
                    183: </sect3>
                    184: 
                    185: <sect3 id="bulk-packages">
                    186: <title>Providing binary packages for ftp.NetBSD.org (bulk-packages)</title>
                    187: <para>
                    188:     We need to coordinate providing a good set of binary packages
                    189:     for as many osrev/arch combinations as possible.
                    190: </para>
                    191:     <para>
                    192:     It is critical to ensure binary packages are built against the
                    193:     same set of depends to avoid install conflicts. The most
                    194:     practical way to arrange this is to use the bulk building system
                    195:     and upload the complete set of packages after every build.
                    196: </para>
                    197:     <para>
                    198:     Developers interested in assisting (all are invited), should
                    199:     subscribe to the pkgsrc-bulk@NetBSD.org list, and check
                    200:     localsrc/admin/bulk-packages for an available arch/osrev
                    201:     combination.
                    202: </para>
                    203: 
                    204:     <sect4 id="conventions">
                    205: <title>bulk-packages conventions:</title>
                    206:     <itemizedlist>
                    207: 
                    208:     <listitem>When taking over an arch/osrev combination either start
                    209:        bulk building from scratch, or download the current set of
                    210:        binary packages from ftp.NetBSD.org to 'pre seed' the
                    211:        build process (most useful for slower architectures).
                    212:     </listitem>
                    213:     <listitem>When uploading packages upload/rsync the entire set of bulk
                    214:        built packages, and delete any other packages for that
                    215:        arch/osrev from ftp.NetBSD.org.
                    216:     </listitem>
                    217: 
                    218:     <listitem>If no longer able to handle a build, remove the entry from
                    219:         localsrc/admin/bulk-packages and notify pkgsrc-bulk.
                    220:     </listitem>
                    221: 
                    222:     <listitem>Any developer can upload updated/new/security-fix packages
                    223:        to ftp.NetBSD.org, but they <emphasis>must</emphasis> be built against
                    224:        the set of binary packages already present for that os/arch.
                    225:     </listitem>
                    226: 
                    227:     <listitem>Machines should run the latest minor release, or (recommended)
                    228:        track the release branch.
                    229:     </listitem>
                    230:     </itemizedlist>
                    231: 
                    232:     <para>
                    233:     Note: This does not address the issue of new versions of binary
                    234:     packages not installing against a user's existing set of
                    235:     installed depends, or a updated depend potentially requiring
                    236:     an update of many other packages already installed in their
                    237:     machine.
                    238:     </para>
                    239:     <para>
                    240:     Current options for that would be either freezing binary packages
                    241:     at tagged values, or having multiple binary package trees per
                    242:     arch/osrev.  The former significantly reduces the
                    243:     utility of the binary packages, and the latter is not worth
                    244:     considering until we can get _one_ consistent tree per arch/osrev.
                    245:     </para>
                    246: </sect4>
                    247: </sect3>
                    248: </sect2>
                    249: 
                    250: 
                    251: <sect2 id="weekly-pkgsrc-checks">
                    252: <title>Weekly pkgsrc checks</title>
                    253: 
                    254: <sect3 id="weeklypkgsrc">
                    255: <title>Weekly-pkgsrc script</title>
                    256: <para>
                    257: 
                    258: <ulink url="mailto:dmcmahill@NetBSD.org">Dan McMahill</ulink> maintains a script that
                    259: is run once a week to perform various pkgsrc consistency checks.  The current
                    260: set of checks are:
                    261: </para>
                    262: <itemizedlist>
                    263: <listitem>DEPENDS &mdash; verifies that all {BUILD_}DEPENDS are set to valid
                    264:   versions.</listitem>
                    265: <listitem>distinfo &mdash; verifies distfile checksums and sizes, and that all
                    266:   patches are listed and their checksums match</listitem>
                    267: <listitem>category makefiles -- verifies all pkgs are listed in the category
                    268:   makefiles.</listitem>
                    269: <listitem>restricted binary pkgs -- warns of any restricted binary
                    270:   pkgs</listitem>
                    271: </itemizedlist>
                    272: <para>
                    273: The results of these checks are emailed to NetBSD pkgsrc developers.
                    274: </para>
                    275: </sect3>
                    276: </sect2>
                    277: 
                    278: <sect2 id="misc">
                    279: <title>Miscellaneous</title>
                    280: 
                    281: <sect3 id="todo">
                    282: <title>Handling the TODO List</title>
                    283: <para>
                    284:   There's a <ulink
                    285:   url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/doc/TODO">TODO</ulink>
                    286:   list in the pkgsrc doc directory. Feel free to add, and especially
                    287:   remove items from there (after solving the mentioned problem, of
                    288:   course).
                    289: </para>
                    290: </sect3>
                    291: 
                    292: <sect3 id="pkg-bug-handler">
                    293: <title>The pkg-bug-handler group</title>
                    294: <para>
                    295:   In order to manage the large number of pkg related problem reports each day,
                    296:   the <quote>pkg-bug-handler</quote> group has been created.  See <ulink
                    297:   url="pkg-bug-handler.html">this page</ulink> for details.
                    298: </para>
                    299: </sect3>
                    300: </sect2>
                    301: </sect1>
                    302: </webpage>

CVSweb <webmaster@jp.NetBSD.org>