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

Bug:
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
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
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> 
22       
23       
24        <sect1>
25                <title>About this chapter</title>
26                 
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>
32
33               
34        </sect1>
35       
36       
37        <sect1 id='about_dports'>
38                <title>About DarwinPorts</title> 
39               
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>
46
47               
48                <para>DarwinPorts is probably best described by comparison:  It's sort
49                of like the <ulink url='http://www.freebsd.org/ports'>FreeBSD ports
50                collection</ulink> or <ulink url='http://fink.sf.org/'>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>
60
61               
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>
78
79
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>
88
89               
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>
100
101               
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>
106
107               
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>
112
113        </sect1>
114       
115       
116        <sect1 id='setup'>
117                <title>Installing DarwinPorts</title>
118               
119                <sect2 id='prerequisites'>
120                        <title>What you need</title>
121                       
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>
130
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>
136
137                </sect2>
138               
139                <sect2 id='getting_dports'>
140                        <title>Obtaining DarwinPorts</title>   
141                       
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 :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od login
157% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od co -P darwinports ]]></programlisting></para>
158                       
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>
162
163                        <para>There is also a <ulink 
164                        url='http://darwinports.opendarwin.org/darwinports-nightly-cvs-snapshot.tar.gz'> 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>
169       
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>
176                       
177                </sect2>
178               
179                <sect2 id='install_dports'>
180                        <title>Installing DarwinPorts</title>
181                       
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>
196
197                <sect2 id='configure_dports'>
198                        <title>Configuring for DarwinPorts</title>
199                       
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>
210
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>
215                       
216                        <para>You should add /opt/local/bin (or wherever you chose to
217                        install DarwinPorts) to your shell's path.</para>
218
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>
222
223                        <para><userinput>export PATH=$PATH:/opt/local/bin</userinput></para>
224
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>
228
229                        <para><userinput>set path=($path /opt/local/bin)</userinput></para>
230       
231                        <para>These changes will not take effect until you have opened a
232                        new shell.</para>
233
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>
243
244                       
245                </sect2>
246
247                <sect2  id='updating_dports'>
248                        <title>Updating DarwinPorts</title>
249                       
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>
257
258                        <variablelist>
259                                <varlistentry>
260                                        <term>Updating your DarwinPorts ports</term>
261
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>
269
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>
275
276                                <varlistentry>
277                                        <term>Updating your DarwinPorts infrastructure</term>
278
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>
292
293        </sect1>
294       
295        <sect1>
296                <title>Using DarwinPorts</title>
297               
298                <sect2 id='port'>
299                        <title>The port command</title>
300
301                        <!--
302
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>
311                       
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>
318                       
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>
324
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>
331
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                        -->
337
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>
343
344                        <para><userinput>sudo port install vile</userinput></para>
345
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>
350
351                        <para>The <userinput>port</userinput> command provides several
352                        other 'actions' that can be performed:</para>
353
354                        <variablelist>
355                                <varlistentry>
356                                        <term>Searching</term>
357                                       
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>
363
364                                                <para><userinput>port search 'vile'</userinput></para>
365
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>
371
372                                <varlistentry>
373                                        <term>Additional Steps: fetch, configure, build, destroot,
374                                        install</term>
375                                               
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>
389
390                                <varlistentry>
391                                        <term>Cleaning a Port</term>
392
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>
398
399                                                <para><userinput>port clean vile</userinput></para>
400                                        </listitem>
401                                </varlistentry>
402
403                                <varlistentry>
404                                        <term>Getting Info about a Port</term>
405
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>
410
411                                                <para><userinput>port info vim</userinput></para>
412                                        </listitem>
413                                </varlistentry>
414
415                                <varlistentry>
416                                        <term>Listing Ports</term>
417
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>
422
423                                                <para><userinput>port search '.+'</userinput></para>
424
425                                                <para>Or, by using the <userinput>list</userinput>
426                                                option:</para>
427
428                                                <para><userinput>port list</userinput></para>
429                                        </listitem>
430                                </varlistentry>
431
432                                <varlistentry>
433                                        <term>Contents of a Port</term>
434
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>
440
441                                                <para><userinput>port contents vile</userinput></para>
442                                        </listitem>
443                                </varlistentry>
444
445                                <varlistentry>
446                                        <term>Variants and Dependencies</term>
447
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>
454
455                                                <para><userinput>port variants vile</userinput></para>
456
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>
460
461                                                <para><userinput>port deps vile</userinput></para>
462                                        </listitem>
463                                </varlistentry>
464                        </variablelist>
465
466                        <para>For more information you should look at the port manpage
467                        by entering: <userinput>man port</userinput>.</para>
468
469                </sect2>
470               
471                <sect2 id='portindex'>
472                        <title>The portindex command</title>
473                       
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>
484
485                </sect2>
486               
487       
488                <sect2 id='uninstall_dports'>
489                        <title>Removing ports</title>
490                       
491                        <para>Ports are removed using the port command described above,
492                        simply execute the command:
493                        <userinput>sudo port uninstall vile</userinput></para>
494
495                </sect2>
496               
497                <sect2 id='upgrade_dports'>
498                        <title>Upgrading ports</title>
499                       
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>
504
505                       
506                </sect2>
507        </sect1>
508       
509       
510        <sect1 id='troubleshooting_use'>
511                <title>Troubleshooting</title>
512               
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='http://www.opendarwin.org/projects/darwinports/en/faq.php'>
517                 FAQ</ulink> first.</para>
518
519                <sect2>
520                        <title>Common errors and problems</title>
521                                       
522                        <sect3 id='E_port_search'>
523                                <title>port search failed: expected integer but got
524                                "PortIndex"</title>
525       
526                                <para>This means your PortIndex file is incorrect or
527                                potentially corrupted, run the <link linkend='portindex'>
528                                portindex</link> command</para>
529
530                               
531                        </sect3>
532                </sect2>
533               
534                <sect2 id='user_bugs'>
535                        <title>Bug reports</title>
536                        <para>If the you have updated your ports tree, searched the
537                        darwinports@opendarwin.org 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>
540
541
542                        <para>The following section describes in some more detail how
543                        to use Bugzilla to submit your port.</para>
544
545                        <sect3>
546                                <title>Submission parameters</title>
547                               
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>
556
557                                                </listitem>
558                                        </varlistentry>
559
560                                        <varlistentry id='Component'>
561                                                <term>
562                                                        Component:
563                                                </term>
564                                                <listitem>
565                                                        <para>Select "dports" as the component. </para>
566
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>
578
579                                                </listitem>
580                                        </varlistentry>
581
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>
589
590                                                </listitem>
591                                        </varlistentry>
592
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>
601
602                                                </listitem>     
603                                        </varlistentry>
604
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>
613
614                                                                <programlisting>
615<![CDATA[Portname-1.2.3
616
617the error log can be found here: URL or ATTACHED or INLINE
618
619Description: What the problem was in a nutshell,
620
621Comments: Any comments you have about the port, bug diagnosis steps,
622concerns, lookouts, dependencies that you may want to mention.
623
624================INLINE CONTENT================
625--
626your sig if you'd like]]> </programlisting>
627                                                               
628                                                </listitem>
629                                        </varlistentry>
630                                </variablelist>
631                        </sect3>
632                </sect2>
633        </sect1>
634</chapter>
Note: See TracBrowser for help on using the repository browser.