source: trunk/doc/guide/xml/user/user.xml @ 8630

Last change on this file since 8630 was 8630, checked in by wbb4, 16 years ago

Submitted by:
Reviewed by:
Approved by:
Obtained from:

Update and clean up the Using DarwinPorts chapter, mainly the installation/configuration, to bring it up to date with Panther :)

  • Property svn:eol-style set to native
File size: 23.0 KB
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "">
4<chapter id="user_info">
5        <chapterinfo>
6                <keywordset>
7                        <keyword>
8                                usage
9                        </keyword>
10                        <keyword>
11                                introduction
12                        </keyword>
13                        <keyword>
14                                user
15                        </keyword>
16                        <keyword>
17                                manual
18                        </keyword>
19                </keywordset>
20        </chapterinfo>
21        <title>Using DarwinPorts</title> 
24        <sect1>
25                <title>About this chapter</title>
27                <para>This document provides a short guide to the basics of the
28                DarwinPorts system. The first section provides a short description
29                of the goals of the project and a brief comparison with other systems.
30                Subsequent sections describe how to get, install, and use DarwinPorts
31                on your own machines. </para>
34        </sect1>
37        <sect1 id='about_dports'>
38                <title>About DarwinPorts</title> 
40                <para>The aim of the DarwinPorts project is to develop a second-
41                generation system for the building, installation and management of
42                third party software. DarwinPorts is mainly developed on Mac OS X,
43                however by design it is quite portable and is intended to work on
44                other UNIX-like systems, especially *BSD and hopefully Linux-based
45                systems.  </para>
48                <para>DarwinPorts is probably best described by comparison:  It's sort
49                of like the <ulink url=''>FreeBSD ports
50                collection</ulink> or <ulink url=''>Fink</ulink> 
51                in that it automates the process of building third party software for
52                Mac OS X and other operating systems.  DarwinPorts also tracks all
53                dependency information for a given piece of software. In other words,
54                it knows what it needs to build and install and in what order for the
55                piece of software you want to work properly. DarwinPorts knows how to
56                make, build and install the software to a specific location, meaning
57                that software installed via DarwinPorts doesn't simply scatter itself
58                all over the system or require user knowledge of dependencies in what
59                order. </para>
62                <para>The FreeBSD Ports Collection is a large set of software packages
63                ported to FreeBSD. The ports collection is also used on the other "free"
64                BSDs. The FreeBSD Ports Collection is based on a large tree of ports
65                where each software has a directory within a category (like mail or
66                graphics). That directory contains the information needed to build the
67                piece of software. DarwinPorts also uses a directory structure like this,
68                although unlike FreeBSD ports the intention is to avoid requiring a
69                complete copy of the 'Ports Tree' on every user's machine.  The FreeBSD
70                Ports Collection is essentially implemented as some very impressive but
71                hairy BSD make(1)'s macros and can be  opaque and non-extensible from
72                the perspective of someone looking to extend or refactor parts of the
73                system.  Given that makefiles aren't the easiest thing to parse or for
74                non-developers to understand, it is also harder to "mine" the FreeBSD
75                ports collection for data to use for other purposes such as
76                generating documentation indexes or arbitrary front-ends for
77                creating or managing ports. </para>
80                <para>A ports collection can be considered an 'expert system' that
81                knows the sources, dependencies, and other information necessary to
82                *build* a given Open Source project.  A package management system relies
83                on similar dependency information, but is focused on safely installing
84                (and de-installing) software.   Before DarwinPorts, most systems did
85                both at once; DarwinPorts, however, is explicitly designed as a pure
86                ports collection which can use various package management systems.
87                </para>
90                <para>Even discounting some of the limitations of The FreeBSD Ports
91                Collection described above, creating automated build systems is rather
92                more complex than it looks at first glance and there's always room for
93                fresh approaches to the problem.  Which is what we have set out to do
94                with DarwinPorts. There are certainly other systems, some of which have
95                already been mentioned, which have made their own attempts at solving
96                this problem. There will likely be many more such systems in the future
97                since trying to find a single solution which pleases everyone is rather
98                like trying to find a single programming language which pleases everyone
99                - it's more or less impossible. </para>
102                <para>DarwinPorts is mostly written in Tcl, with some components written
103                in C. Tcl was chosen to allow DarwinPorts to be readily embedded in other
104                applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read
105                Portfiles. </para>
108                <para>Even though DarwinPorts is written in Tcl, users do not need to know
109                Tcl in order to use the system or even to add new ports.  Port description
110                files, though they are actually full Tcl programs in their own right, are
111                designed to look like a simple list of key/value pairs. </para>
113        </sect1>
116        <sect1 id='setup'>
117                <title>Installing DarwinPorts</title>
119                <sect2 id='prerequisites'>
120                        <title>What you need</title>
122                        <para>DarwinPorts primary target platform is Mac OS X 10.3
123                        "Panther" or later (i.e. Darwin 7.0 or later).  However,
124                        DarwinPorts should still work on Mac OS X 10.2 "Jaguar", although
125                        most ports are no longer tested on Jaguar.  DarwinPorts is also
126                        known to work on various other operating systems such as FreeBSD,
127                        NetBSD, OpenBSD, and various Linux distributions.  These
128                        instructions should enable DarwinPorts to be installed on any of
129                        these platforms.</para>
131                        <para>To install and use DarwinPorts you must install the Developer
132                        tools (gcc, autoconf etc on other platforms, also known as the
133                        "Xcode tools" on Mac OS X 10.3.)  All the other prerequisites are
134                        pre-installed on Mac OS X 10.2 and later. On other platforms you
135                        will need to ensure you have installed Tcl (8.3 or later). </para>
137                </sect2>
139                <sect2 id='getting_dports'>
140                        <title>Obtaining DarwinPorts</title>   
142                        <para>Currently the main way to get DarwinPorts is by using the Concurrent
143                        Versioning System (cvs). CVS is installed with the Developers Tools on Mac
144                        OS X. To download DarwinPorts using cvs you should use the following
145                        Terminal commands. At this time you must keep the darwinports directoy
146                        that is downloaded on your machine, even after installation as it also
147                        contains all the port description files (Portfiles). In the future these
148                        will be automatically downloaded as they are needed so you won't need to
149                        keep the directory. Choose a location for DarwinPorts where you won't
150                        want/need to move it. For the rest of the document I will assume the user
151                        name is 'mike' and the DarwinPorts infrastructure is going to be
152                        downloaded to a directory (folder) called darwinports in your home
153                        directory (i.e. /Users/mike/darwinports/) you should replace the username
154                        with your own username and edit the commands I give so they work
155                        correctly on your installation. <programlisting><![CDATA[% cd ~/
156% cvs -d login
157% cvs -d co -P darwinports ]]></programlisting></para>
159                        <para>These commands first ensure you are currently in your home
160                        directory, then log onto the opendarwin cvs server and finally
161                        'checkout' (download) DarwinPorts. </para>
163                        <para>There is also a <ulink 
164                        url=''> cvs snapshot</ulink> 
165                        available that is made from cvs every 6 hours. The tarball is made
166                        from a anonymous checkout of DarwinPorts so you can still use the
167                        commands below for <link linkend='updating_dports'>updating</link>.
168                        </para>
170                        <para>In the near future we will provide a binary installer for
171                        DarwinPorts and the source files downloadable directly from the
172                        website rather than requiring users to use cvs. CVS is likely to
173                        remain important for users who want to closely track the latest
174                        ports as it can be used to update your port descriptions (and
175                        is currently the only way to do so). </para>
177                </sect2>
179                <sect2 id='install_dports'>
180                        <title>Installing DarwinPorts</title>
182                        <para>To install DarwinPorts execute the following commands from the
183                        darwinports/base directory.  These commands assume that you checked
184                        out the darwinports tree from CVS in your home directory.  Modify
185                        the <userinput>cd</userinput> command appropriately if you did
186                        otherwise.
187                        <programlisting><![CDATA[% cd ~/darwinports/base
188% ./configure
189% make
190% sudo make install]]></programlisting>
191                        This will compile and install all the necessary software. In order
192                        to install DarwinPorts on *BSD the default group-ownership must be
193                        passed to each make command: <userinput>make DSTGRP=wheel
194                        </userinput>.</para>
195                </sect2>
197                <sect2 id='configure_dports'>
198                        <title>Configuring for DarwinPorts</title>
200                        <para>It is no longer necessary to edit
201                        <filename>/etc/ports/sources.conf</filename> after installing
202                        DarwinPorts.  If you change the location of the
203                        <filename>dports</filename> directory, which was in
204                        <filename>~/darwinports/dports</filename> based on the above
205                        examples, then you will still need to edit
206                        <filename>/etc/ports/sources.conf</filename> and modify the
207                        <userinput>file:///Users/mike/darwinports/dports</userinput> line
208                        to reflect the new location.  To edit the file you must use a
209                        command line text editor like pico or vi. </para>
211                        <note><para>Please note, if you are using Mac OS X 10.2 "Jaguar", then
212                                you will need to edit <filename>/etc/ports/ports.conf</filename> and
213                                change: <computeroutput>portinstalltype image</computeroutput>
214                                to: <userinput>portinstalltype direct</userinput></para></note>
216                        <para>You should add /opt/local/bin (or wherever you chose to
217                        install DarwinPorts) to your shell's path.</para>
219                        <para>If you are using Mac OS X 10.3 "Panther" or a Bourne shell
220                        (bash, zsh), add the following line to your
221                        <filename>~/.profile</filename>:</para>
223                        <para><userinput>export PATH=$PATH:/opt/local/bin</userinput></para>
225                        <para>If you are using Mac OS X 10.2 "Jaguar" or a C shell (tcsh),
226                        add the following line to your
227                        <filename>~/.cshrc</filename>:</para>
229                        <para><userinput>set path=($path /opt/local/bin)</userinput></para>
231                        <para>These changes will not take effect until you have opened a
232                        new shell.</para>
234                        <para>Once you have got this far, you should have a working
235                        installation of DarwinPorts, you have installed the 'port'
236                        command (by default this installed as
237                        <filename>/opt/local/bin/port</filename>)
238                        and the libraries it needs (in
239                        <filename>/opt/local/share/darwinports</filename> 
240                        and <filename>/Library/Tcl/darwinports1.0</filename> by
241                        default.)
242                        </para>
245                </sect2>
247                <sect2  id='updating_dports'>
248                        <title>Updating DarwinPorts</title>
250                        <para>New ports are always being added to the DarwinPorts dports
251                        tree, you should regularly update your tree to get access to new
252                        ports, and (hopefully) improved versions of current ports.  Currently
253                        the simplest way you can update the dports tree is to use
254                        <command>cvs</command>.  You can also use <command>cvs</command>
255                        to fetch a new version of the DarwinPorts infrastructure (eg the
256                        <command>port</command> command and associated libraries).</para>
258                        <variablelist>
259                                <varlistentry>
260                                        <term>Updating your DarwinPorts ports</term>
262                                        <listitem>
263                                                <para>To get the latest Portfiles (the instructions for
264                                                        building ports), you need to update your
265                                                        <filename>dports</filename> tree from
266                                                        <command>cvs</command>:
267                                                        <programlisting><![CDATA[% cd ~/darwinports/dports
268% cvs -q -z3 update -dP]]></programlisting></para>
270                                                <para>By using the -q flag to
271                                                        <command>cvs</command>, you will see in the output what
272                                                        Ports have changed or have been added.</para>
273                                        </listitem>             
274                                </varlistentry>
276                                <varlistentry>
277                                        <term>Updating your DarwinPorts infrastructure</term>
279                                        <listitem>
280                                                <para>To get the latest DarwinPorts infrastructure (or
281                                                        "base") for building ports, you need to update your
282                                                        <filename>base</filename> from <command>cvs</command>:
283                                                        <programlisting><![CDATA[% cd ~/darwinports/base
284% cvs -q -z3 update -dP
285% ./configure
286% make clean && make
287% sudo make install]]></programlisting></para>
288                                        </listitem>
289                                </varlistentry>
290                        </variablelist>
291                </sect2>
293        </sect1>
295        <sect1>
296                <title>Using DarwinPorts</title>
298                <sect2 id='port'>
299                        <title>The port command</title>
301                        <!--
303                        <para>Using DarwinPorts is very straightforward, most of the time
304                        all you need to do is execute a single command to install a port.
305                        For example, if you want to install the text editor vile, you'd
306                        simply execute the command <userinput>sudo port install vile
307                        </userinput>. That will fetch, build and install vim and anything
308                        else vim needs to work. All of the examples below use the vile
309                        port as an example, you should use whatever port you actually
310                        want to install.</para>
312                        <para>If you aren't sure of the exact name of your port you can
313                        use the search feature. For example, if you wanted to find out
314                        if there was anything called vile in the ports you could do:
315                        <userinput>port search 'vile'</userinput>. The search facility
316                        uses standard regular expression syntax, so you can list all
317                        the ports by doing: <userinput>port search '.+'</userinput>.</para>
319                        <para>You can see more detail of what is happening when you
320                        install a port by using the verbose (-v), or debug (-d) flags
321                        when using the port install command, to see all the possible
322                        output use them both together: <userinput>port -v -d install
323                        vile</userinput>. </para>
325                        <para>You may break up the installation of a port into a number of
326                        steps, fetch, checksum, configure, build, and finally install. Each
327                        of these steps performs a part of the process to install a port,
328                        using the steps individually is however not normally needed unless
329                        you are developing a new port or are trying to diagnose a
330                        problem. </para>
332                        <para>Once the port has been installed, you may want to delete
333                        all the intermediate files that DarwinPorts has created while
334                        building the port, to do this you should enter:
335                        <userinput>port clean vile</userinput>.</para>
336                        -->
338                        <para>Using the DarwinPorts <userinput>port</userinput> command is
339                        very straight-forward.  Most of the time all you need to do is
340                        execute a single command to install a port.  For example, if you
341                        want to install the text editor vile, you would simply
342                        type:</para>
344                        <para><userinput>sudo port install vile</userinput></para>
346                        <para>That will fetch, build and install vile and anything else it
347                        needs to work.  All of the examples below use the vile for as an
348                        example.  You should use whatever port you actually want
349                        to install.</para>
351                        <para>The <userinput>port</userinput> command provides several
352                        other 'actions' that can be performed:</para>
354                        <variablelist>
355                                <varlistentry>
356                                        <term>Searching</term>
358                                        <listitem>
359                                                <para>If you aren't sure the exact name of the port you
360                                                want, you can use the <userinput>search</userinput> option.
361                                                For example, if you wanted to find out if there was anything
362                                                called vile in in the ports, you could do:</para>
364                                                <para><userinput>port search 'vile'</userinput></para>
366                                                <para>The search facility uses standard regular expression
367                                                syntax, so you can also do much more complex
368                                                searches.</para>
369                                        </listitem>
370                                </varlistentry>
372                                <varlistentry>
373                                        <term>Additional Steps: fetch, configure, build, destroot,
374                                        install</term>
376                                        <listitem>
377                                                <para>You may want to break up the installation of a port
378                                                into a number of steps.  <userinput>fetch</userinput>,
379                                                <userinput>configure</userinput>,
380                                                <userinput>build</userinput>,
381                                                <userinput>destroot</userinput> and finally
382                                                <userinput>install</userinput> are all available and perform
383                                                part of the build or install process.  Using the steps
384                                                individually is not normally needeed unless you are
385                                                developing a new port or trying to diagnose a
386                                                problem.</para>
387                                        </listitem>
388                                </varlistentry>
390                                <varlistentry>
391                                        <term>Cleaning a Port</term>
393                                        <listitem>
394                                                <para>Once the port has been installed, you may want to
395                                                delete all the intermediate files that DarwinPorts has
396                                                created while building the port.  To do this, simply use the
397                                                <userinput>clean</userinput> option:</para>
399                                                <para><userinput>port clean vile</userinput></para>
400                                        </listitem>
401                                </varlistentry>
403                                <varlistentry>
404                                        <term>Getting Info about a Port</term>
406                                        <listitem>
407                                                <para>You may want to get information about a port, such as
408                                                a description, its maintainer, and more.  You can do this by
409                                                using the <userinput>info</userinput> option:</para>
411                                                <para><userinput>port info vim</userinput></para>
412                                        </listitem>
413                                </varlistentry>
415                                <varlistentry>
416                                        <term>Listing Ports</term>
418                                        <listitem>
419                                                <para>You may want a list of all the ports that are
420                                                available.  You can do this two ways, first by using the
421                                                <userinput>search</userinput> option:</para>
423                                                <para><userinput>port search '.+'</userinput></para>
425                                                <para>Or, by using the <userinput>list</userinput>
426                                                option:</para>
428                                                <para><userinput>port list</userinput></para>
429                                        </listitem>
430                                </varlistentry>
432                                <varlistentry>
433                                        <term>Contents of a Port</term>
435                                        <listitem>
436                                                <para>Once the port has been installed, you might want to
437                                                check what files are associated with that port.  The
438                                                <userinput>contents</userinput> option will list all of the
439                                                files that were installed by the port:</para>
441                                                <para><userinput>port contents vile</userinput></para>
442                                        </listitem>
443                                </varlistentry>
445                                <varlistentry>
446                                        <term>Variants and Dependencies</term>
448                                        <listitem>
449                                                <para>Before you install a port, you may want to check what
450                                                variations of that port are available to use.  Variants
451                                                provide additional configuration options for a port.  To see
452                                                what variations a port has, use the
453                                                <userinput>variants</userinput> option:</para>
455                                                <para><userinput>port variants vile</userinput></para>
457                                                <para>You also may want to see what dependencies a port has.
458                                                You can use the <userinput>deps</userinput> option to
459                                                check:</para>
461                                                <para><userinput>port deps vile</userinput></para>
462                                        </listitem>
463                                </varlistentry>
464                        </variablelist>
466                        <para>For more information you should look at the port manpage
467                        by entering: <userinput>man port</userinput>.</para>
469                </sect2>
471                <sect2 id='portindex'>
472                        <title>The portindex command</title>
474                        <para>Most of the time you won't need to use this command as
475                        it is used to build the index of all the available ports, but
476                        sometimes the index you have is out of date or innacurate for
477                        some reason. When this occurs you will get an error message
478                        like 'port search failed: expected integer but got "PortIndex"'.
479                        You can fix problem by moving to the dports directory
480                        (/Users/mike/darwinports/dports in our examples) and
481                        executing: <userinput>portindex</userinput>. This will go
482                        through all the available ports in the dport directory and
483                        build an index file called PortIndex.</para>
485                </sect2>
488                <sect2 id='uninstall_dports'>
489                        <title>Removing ports</title>
491                        <para>Ports are removed using the port command described above,
492                        simply execute the command:
493                        <userinput>sudo port uninstall vile</userinput></para>
495                </sect2>
497                <sect2 id='upgrade_dports'>
498                        <title>Upgrading ports</title>
500                        <para>At the moment there is not a 'port upgrade' command so
501                        to upgrade a port you must uninstall and then install it again.
502                        <programlisting><![CDATA[% sudo port uninstall vile
503% sudo port install vile]]></programlisting></para>
506                </sect2>
507        </sect1>
510        <sect1 id='troubleshooting_use'>
511                <title>Troubleshooting</title>
513                <para>There are a number of common problems so before you report a
514                problem (details on how to <link linkend='user_bugs'>report problems</link>
515                 follow) check that the problem is described here, or in the
516                 <ulink url=''>
517                 FAQ</ulink> first.</para>
519                <sect2>
520                        <title>Common errors and problems</title>
522                        <sect3 id='E_port_search'>
523                                <title>port search failed: expected integer but got
524                                "PortIndex"</title>
526                                <para>This means your PortIndex file is incorrect or
527                                potentially corrupted, run the <link linkend='portindex'>
528                                portindex</link> command</para>
531                        </sect3>
532                </sect2>
534                <sect2 id='user_bugs'>
535                        <title>Bug reports</title>
536                        <para>If the you have updated your ports tree, searched the
537               mailling list archives and read the
538                        common problems and the FAQ and you still can't find the answer
539                        to the problem, you should submit a bug report via bugzilla.</para>
542                        <para>The following section describes in some more detail how
543                        to use Bugzilla to submit your port.</para>
545                        <sect3>
546                                <title>Submission parameters</title>
548                                <variablelist>
549                                        <varlistentry id='Project'>
550                                                <term>
551                                                        Project:
552                                                </term>
553                                                <listitem>
554                                                        <para>Make sure you select the DarwinPorts
555                                                        project.</para>
557                                                </listitem>
558                                        </varlistentry>
560                                        <varlistentry id='Component'>
561                                                <term>
562                                                        Component:
563                                                </term>
564                                                <listitem>
565                                                        <para>Select "dports" as the component. </para>
567                                                </listitem>
568                                        </varlistentry>
569                                        <varlistentry id='Assigned_to'>
570                                                <term>
571                                                        Assigned to:
572                                                </term>
573                                                <listitem>
574                                                        <para>Please assign updates, bug reports and
575                                                        comments on existing ports to the maintainer.
576                                                        Otherwise, if this is a new port or an RFC,
577                                                        please leave blank</para>
579                                                </listitem>
580                                        </varlistentry>
582                                        <varlistentry id='URL'>
583                                                <term>
584                                                        URL:
585                                                </term>
586                                                <listitem>
587                                                        <para>You may use this field to point to the
588                                                        port output if it is available online.</para>
590                                                </listitem>
591                                        </varlistentry>
593                                        <varlistentry id='Summary'>
594                                                <term>
595                                                        Summary:
596                                                </term>
597                                                <listitem>
598                                                <para>Please use this format
599                                                <userinput>BUG: portname-1.2.3</userinput> for
600                                                the submission of port installation failures. </para>
602                                                </listitem>     
603                                        </varlistentry>
605                                        <varlistentry id='Description'>
606                                                <term>
607                                                        Description:
608                                                </term>
609                                                <listitem>
610                                                        <para>The description field should contain the
611                                                        following information as per the example given
612                                                        here here. </para>
614                                                                <programlisting>
617the error log can be found here: URL or ATTACHED or INLINE
619Description: What the problem was in a nutshell,
621Comments: Any comments you have about the port, bug diagnosis steps,
622concerns, lookouts, dependencies that you may want to mention.
624================INLINE CONTENT================
626your sig if you'd like]]> </programlisting>
628                                                </listitem>
629                                        </varlistentry>
630                                </variablelist>
631                        </sect3>
632                </sect2>
633        </sect1>
Note: See TracBrowser for help on using the repository browser.