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

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

Bug: 2207
Submitted by: skuld@…
Reviewed by:
Approved by:
Obtained from:

Update the Guide to instruct Jaguar users on what to do in order to disable image functionality so that DarwinPorts works, basically changing "image" install to "direct" in ports.conf.

  • Property svn:eol-style set to native
File size: 21.9 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>Currently DarwinPorts is only supported on Mac OS X 10.2 or later
123                        (i.e., Darwin 6.0 or later).   However, these instructions should also
124                        enable it to  work on FreeBSD and NetBSD, at least most of the time;
125                        not every build of DarwinPorts is tested on those platforms, so some
126                        minor breakage may creep in from time to time.</para>
127
128
129                        <para>To install and use DarwinPorts you must install the Developer
130                        tools (gcc, autoconf etc on other platforms). All the other
131                        prerequisites are pre-installed on Mac OS X 10.2 and later. On other
132                        platforms you will need to ensure you have installed Tcl (8.3 or
133                        later). </para>
134
135                       
136                </sect2>
137               
138                <sect2 id='getting_dports'>
139                        <title>Obtaining DarwinPorts</title>   
140                       
141                        <para>Currently the main way to get DarwinPorts is by using the Concurrent
142                        Versioning System (cvs). CVS is installed with the Developers Tools on Mac
143                        OS X. To download DarwinPorts using cvs you should use the following
144                        Terminal commands. At this time you must keep the darwinports directoy
145                        that is downloaded on your machine, even after installation as it also
146                        contains all the port description files (Portfiles). In the future these
147                        will be automatically downloaded as they are needed so you won't need to
148                        keep the directory. Choose a location for DarwinPorts where you won't
149                        want/need to move it. For the rest of the document I will assume the user
150                        name is 'mike' and the DarwinPorts infrastructure is going to be
151                        downloaded to a directory (folder) called darwinports in your home
152                        directory (i.e. /Users/mike/darwinports/) you should replace the username
153                        with your own username and edit the commands I give so they work
154                        correctly on your installation. <programlisting><![CDATA[
155 
156% cd ~/
157% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od login
158% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od co -P darwinports
159]]>
160                                </programlisting></para>
161       
162                       
163                        <para>These commands first ensure you are currently in your home
164                        directory, then log onto the opendarwin cvs server and finally
165                        'checkout' (download) DarwinPorts. </para>
166
167                        <para>There is also a <ulink 
168                        url='http://darwinports.opendarwin.org/darwinports-nightly-cvs-snapshot.tar.gz'> cvs snapshot</ulink> 
169                        available that is made from cvs every 6 hours. The tarball is made
170                        from a anonymous checkout of DarwinPorts so you can still use the
171                        commands below for <link linkend='updating_dports'>updating</link>.
172                        </para>
173       
174                        <para>In the near future we will provide a binary installer for
175                        DarwinPorts and the source files downloadable directly from the
176                        website rather than requiring users to use cvs. CVS is likely to
177                        remain important for users who want to closely track the latest
178                        ports as it can be used to update your port descriptions (and
179                        is currently the only way to do so). </para>
180
181                       
182                </sect2>
183               
184                <sect2 id='install_dports'>
185                        <title>Installing DarwinPorts</title>
186                       
187                        <para>To install DarwinPorts execute the following commands from the
188                        darwinports/base directory.  These commands assume that you checked
189                        out the darwinports tree from CVS in your home directory.  Modify
190                        the <userinput>cd</userinput> command appropriately if you did
191                        otherwise.
192                        <programlisting><![CDATA[
193% cd ~/darwinports/base
194% ./configure
195% make
196% sudo make install
197]]>
198                        </programlisting>
199                        This will compile and install all the necessary software. In order
200                        to install DarwinPorts on *BSD the default group-ownership must be
201                        passed to each make command: <userinput>make DSTGRP=wheel
202                        </userinput>.</para>
203
204                       
205                        <para>To configure DarwinPorts you should edit
206                        /etc/ports/sources.conf. The sources.conf lists the location of
207                        both local and remote port software hierarchies (Currently there is
208                        not a remote repository). Add an entry for your local ports tree:
209                        <userinput>file:///Users/mike/darwinports/dports</userinput>. To
210                        edit the file you must use a command line text editor like pico
211                        or vi. </para>
212
213                        <para>Please note, if you are using Mac OS X 10.2 "Jaguar", then
214                                you will need to edit <file>/etc/ports/ports.conf</file> and
215                                change: <computeroutput>portinstalltype image</computeroutput>
216                                to: <userinput>portinstalltype direct</userinput></para>
217                       
218                        <para>You should add /opt/local/bin (or wherever you chose to
219                        install DarwinPorts) to your path. If you aren't sure how, add
220                        <userinput>set path=($path /opt/local/bin)</userinput> to your
221                        .cshrc file. You may need to create the file first if you
222                        haven't set one up before. Then close the Terminal window and
223                        open a new one so the new path setting takes effect.</para>
224
225                       
226                        <para>Once you have got this far, you should have a working
227                        installation of DarwinPorts, you have installed the 'port'
228                        command (by default this installed as /opt/local/bin/port)
229                        and the libraries it needs (in /opt/local/share/darwinports
230                        and /System/Library/Tcl/8.3/darwinports1.0 by default.
231                        </para>
232
233                       
234                </sect2>
235        </sect1>
236       
237       
238        <sect1>
239                <title>Using DarwinPorts</title>
240               
241                <sect2 id='port'>
242                        <title>The port command</title>
243
244                        <!--
245
246                        <para>Using DarwinPorts is very straightforward, most of the time
247                        all you need to do is execute a single command to install a port.
248                        For example, if you want to install the text editor vile, you'd
249                        simply execute the command <userinput>sudo port install vile
250                        </userinput>. That will fetch, build and install vim and anything
251                        else vim needs to work. All of the examples below use the vile
252                        port as an example, you should use whatever port you actually
253                        want to install.</para>
254                       
255                        <para>If you aren't sure of the exact name of your port you can
256                        use the search feature. For example, if you wanted to find out
257                        if there was anything called vile in the ports you could do:
258                        <userinput>port search 'vile'</userinput>. The search facility
259                        uses standard regular expression syntax, so you can list all
260                        the ports by doing: <userinput>port search '.+'</userinput>.</para>
261                       
262                        <para>You can see more detail of what is happening when you
263                        install a port by using the verbose (-v), or debug (-d) flags
264                        when using the port install command, to see all the possible
265                        output use them both together: <userinput>port -v -d install
266                        vile</userinput>. </para>
267
268                        <para>You may break up the installation of a port into a number of
269                        steps, fetch, checksum, configure, build, and finally install. Each
270                        of these steps performs a part of the process to install a port,
271                        using the steps individually is however not normally needed unless
272                        you are developing a new port or are trying to diagnose a
273                        problem. </para>
274
275                        <para>Once the port has been installed, you may want to delete
276                        all the intermediate files that DarwinPorts has created while
277                        building the port, to do this you should enter:
278                        <userinput>port clean vile</userinput>.</para>
279                        -->
280
281                        <para>Using the DarwinPorts <userinput>port</userinput> command is
282                        very straight-forward.  Most of the time all you need to do is
283                        execute a single command to install a port.  For example, if you
284                        want to install the text editor vile, you would simply
285                        type:</para>
286
287                        <para><userinput>sudo port install vile</userinput></para>
288
289                        <para>That will fetch, build and install vile and anything else it
290                        needs to work.  All of the examples below use the vile for as an
291                        example.  You should use whatever port you actually want
292                        to install.</para>
293
294                        <para>The <userinput>port</userinput> command provides several
295                        other 'actions' that can be performed:</para>
296
297                        <variablelist>
298                                <varlistentry>
299                                        <term>Searching</term>
300                                       
301                                        <listitem>
302                                                <para>If you aren't sure the exact name of the port you
303                                                want, you can use the <userinput>search</userinput> option.
304                                                For example, if you wanted to find out if there was anything
305                                                called vile in in the ports, you could do:</para>
306
307                                                <para><userinput>port search 'vile'</userinput></para>
308
309                                                <para>The search facility uses standard regular expression
310                                                syntax, so you can also do much more complex
311                                                searches.</para>
312                                        </listitem>
313                                </varlistentry>
314
315                                <varlistentry>
316                                        <term>Additional Steps: fetch, configure, build, destroot,
317                                        install</term>
318                                               
319                                        <listitem>
320                                                <para>You may want to break up the installation of a port
321                                                into a number of steps.  <userinput>fetch</userinput>,
322                                                <userinput>configure</userinput>,
323                                                <userinput>build</userinput>,
324                                                <userinput>destroot</userinput> and finally
325                                                <userinput>install</userinput> are all available and perform
326                                                part of the build or install process.  Using the steps
327                                                individually is not normally needeed unless you are
328                                                developing a new port or trying to diagnose a
329                                                problem.</para>
330                                        </listitem>
331                                </varlistentry>
332
333                                <varlistentry>
334                                        <term>Cleaning a Port</term>
335
336                                        <listitem>
337                                                <para>Once the port has been installed, you may want to
338                                                delete all the intermediate files that DarwinPorts has
339                                                created while building the port.  To do this, simply use the
340                                                <userinput>clean</userinput> option:</para>
341
342                                                <para><userinput>port clean vile</userinput></para>
343                                        </listitem>
344                                </varlistentry>
345
346                                <varlistentry>
347                                        <term>Listing Ports</term>
348
349                                        <listitem>
350                                                <para>You may want a list of all the ports that are
351                                                available.  You can do this two ways, first by using the
352                                                <userinput>search</userinput> option:</para>
353
354                                                <para><userinput>port search '.+'</userinput></para>
355
356                                                <para>Or, by using the <userinput>list</userinput>
357                                                option:</para>
358
359                                                <para><userinput>port list</userinput></para>
360                                        </listitem>
361                                </varlistentry>
362
363                                <varlistentry>
364                                        <term>Contents of a Port</term>
365
366                                        <listitem>
367                                                <para>Once the port has been installed, you might want to
368                                                check what files are associated with that port.  The
369                                                <userinput>contents</userinput> option will list all of the
370                                                files that were installed by the port:</para>
371
372                                                <para><userinput>port contents vile</userinput></para>
373                                        </listitem>
374                                </varlistentry>
375
376                                <varlistentry>
377                                        <term>Variants and Dependencies</term>
378
379                                        <listitem>
380                                                <para>Before you install a port, you may want to check what
381                                                variations of that port are available to use.  Variants
382                                                provide additional configuration options for a port.  To see
383                                                what variations a port has, use the
384                                                <userinput>variants</userinput> option:</para>
385
386                                                <para><userinput>port variants vile</userinput></para>
387
388                                                <para>You also may want to see what dependencies a port has.
389                                                You can use the <userinput>deps</userinput> option to
390                                                check:</para>
391
392                                                <para><userinput>port deps vile</userinput></para>
393                                        </listitem>
394                                </varlistentry>
395                        </variablelist>
396
397                        <para>For more information you should look at the port manpage
398                        by entering: <userinput>man port</userinput>.</para>
399
400                </sect2>
401               
402                <sect2 id='portindex'>
403                        <title>The portindex command</title>
404                       
405                        <para>Most of the time you won't need to use this command as
406                        it is used to build the index of all the available ports, but
407                        sometimes the index you have is out of date or innacurate for
408                        some reason. When this occurs you will get an error message
409                        like 'port search failed: expected integer but got "PortIndex"'.
410                        You can fix problem by moving to the dports directory
411                        (/Users/mike/darwinports/dports in our examples) and
412                        executing: <userinput>portindex</userinput>. This will go
413                        through all the available ports in the dport directory and
414                        build an index file called PortIndex.</para>
415
416                       
417                </sect2>
418               
419                <sect2  id='updating_dports'>
420                        <title>Updating DarwinPorts</title>
421                       
422                        <para>New ports are always being added to the DarwinPorts dports
423                        tree, you should regularly update your tree to get access to new
424                        ports, and (hopefully) improved versions of current ports.  Currently
425                        the simplest way you can update the dports tree is to use
426                        <command>cvs</command>.  You can also use <command>cvs</command>
427                        to fetch a new version of the DarwinPorts infrastructure (eg the
428                        <command>port</command> command and associated libraries).</para>
429
430                        <variablelist>
431                                <varlistentry>
432                                        <term>Updating your DarwinPorts ports</term>
433
434                                        <listitem>
435                                                <para>To get the latest Portfiles (the instructions for
436                                                        building ports), you need to update your
437                                                        <filename>dports</filename> tree from
438                                                        <command>cvs</command>:
439                                                        <programlisting><![CDATA[
440% cd ~/darwinports/dports
441% cvs -q -z3 update -dP
442]]>
443                                                        </programlisting></para>
444
445                                                <para>By using the -q flag to
446                                                        <command>cvs</command>, you will see in the output what
447                                                        Ports have changed or have been added.</para>
448                                        </listitem>             
449                                </varlistentry>
450
451                                <varlistentry>
452                                        <term>Updating your DarwinPorts infrastructure</term>
453
454                                        <listitem>
455                                                <para>To get the latest DarwinPorts infrastructure (or
456                                                        "base") for building ports, you need to update your
457                                                        <filename>base</filename> from <command>cvs</command>:
458                                                        <programlisting><![CDATA[
459% cd ~/darwinports/base
460% cvs -q -z3 update -dP
461% ./configure
462% make clean && make
463% sudo make install
464]]>
465                                                        </programlisting></para>
466                                        </listitem>
467                                </varlistentry>
468                        </variablelist>
469                </sect2>
470               
471                <sect2 id='uninstall_dports'>
472                        <title>Removing ports</title>
473                       
474                        <para>Ports are removed using the port command described above,
475                        simply execute the command:
476                        <userinput>sudo port uninstall vile</userinput></para>
477
478                </sect2>
479               
480                <sect2 id='upgrade_dports'>
481                        <title>Upgrading ports</title>
482                       
483                        <para>At the moment there is not a 'port upgrade' command so
484                        to upgrade a port you must uninstall and then install it again.
485                        <programlisting><![CDATA[
486 
487% sudo port uninstall vile
488% sudo port install vile
489]]>
490                                </programlisting></para>
491
492                       
493                </sect2>
494        </sect1>
495       
496       
497        <sect1 id='troubleshooting_use'>
498                <title>Troubleshooting</title>
499               
500                <para>There are a number of common problems so before you report a
501                problem (details on how to <link linkend='user_bugs'>report problems</link>
502                 follow) check that the problem is described here, or in the
503                 <ulink url='http://www.opendarwin.org/projects/darwinports/en/faq.php'>
504                 FAQ</ulink> first.</para>
505
506                <sect2>
507                        <title>Common errors and problems</title>
508                                       
509                        <sect3 id='E_port_search'>
510                                <title>port search failed: expected integer but got
511                                "PortIndex"</title>
512       
513                                <para>This means your PortIndex file is incorrect or
514                                potentially corrupted, run the <link linkend='portindex'>
515                                portindex</link> command</para>
516
517                               
518                        </sect3>
519                </sect2>
520               
521                <sect2 id='user_bugs'>
522                        <title>Bug reports</title>
523                        <para>If the you have updated your ports tree, searched the
524                        darwinports@opendarwin.org mailling list archives and read the
525                        common problems and the FAQ and you still can't find the answer
526                        to the problem, you should submit a bug report via bugzilla.</para>
527
528
529                        <para>The following section describes in some more detail how
530                        to use Bugzilla to submit your port.</para>
531
532                        <sect3>
533                                <title>Submission parameters</title>
534                               
535                                <variablelist>
536                                        <varlistentry id='Project'>
537                                                <term>
538                                                        Project:
539                                                </term>
540                                                <listitem>
541                                                        <para>Make sure you select the DarwinPorts
542                                                        project.</para>
543
544                                                </listitem>
545                                        </varlistentry>
546
547                                        <varlistentry id='Component'>
548                                                <term>
549                                                        Component:
550                                                </term>
551                                                <listitem>
552                                                        <para>Select "dports" as the component. </para>
553
554                                                </listitem>
555                                        </varlistentry>
556                                        <varlistentry id='Assigned_to'>
557                                                <term>
558                                                        Assigned to:
559                                                </term>
560                                                <listitem>
561                                                        <para>Please assign updates, bug reports and
562                                                        comments on existing ports to the maintainer.
563                                                        Otherwise, if this is a new port or an RFC,
564                                                        please leave blank</para>
565
566                                                </listitem>
567                                        </varlistentry>
568
569                                        <varlistentry id='URL'>
570                                                <term>
571                                                        URL:
572                                                </term>
573                                                <listitem>
574                                                        <para>You may use this field to point to the
575                                                        port output if it is available online.</para>
576
577                                                </listitem>
578                                        </varlistentry>
579
580                                        <varlistentry id='Summary'>
581                                                <term>
582                                                        Summary:
583                                                </term>
584                                                <listitem>
585                                                <para>Please use this format
586                                                <userinput>BUG: portname-1.2.3</userinput> for
587                                                the submission of port installation failures. </para>
588
589                                                </listitem>     
590                                        </varlistentry>
591
592                                        <varlistentry id='Description'>
593                                                <term>
594                                                        Description:
595                                                </term>
596                                                <listitem>
597                                                        <para>The description field should contain the
598                                                        following information as per the example given
599                                                        here here. </para>
600
601                                                                <programlisting>
602<![CDATA[
603Portname-1.2.3
604
605the error log can be found here: URL or ATTACHED or INLINE
606
607Description: What the problem was in a nutshell,
608
609Comments: Any comments you have about the port, bug diagnosis steps,
610concerns, lookouts, dependencies that you may want to mention.
611
612================INLINE CONTENT================
613--
614your sig if you'd like
615]]> 
616                                                </programlisting>
617                                                               
618                                                </listitem>
619                                        </varlistentry>
620                                </variablelist>
621                        </sect3>
622                </sect2>
623        </sect1>
624</chapter>
Note: See TracBrowser for help on using the repository browser.