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

Last change on this file since 2621 was 2621, checked in by michaelm, 17 years ago

first draft of user level chapter of the guide

  • Property svn:eol-style set to native
File size: 14.1 KB
Line 
1<?xml version="1.0" encoding="iso-8859-1" ?>
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 will provide a short guide to the basics of the DarwinPorts system. The first section will provide a short description of the goals of the project and a brief comparison with other systems. Subsequent sections will describe how to get, install and use DarwinPorts on your own machines.
28                </para>
29               
30        </sect1>
31       
32       
33        <sect1 id='about_dports'>
34                <title>About DarwinPorts</title> 
35               
36                <para>The aim of the DarwinPorts project is to develop a second generation system for the building, installation and management of third party software. DarwinPorts is mainly developed on Mac OS X, however by design it is quite portable and is intended to work on other unix-like systems, especially *BSD and hopefully linux based systems. 
37                </para>
38               
39                <para>DarwinPorts is probably best described by comparison:  It's sort of like the <ulink url='http://www.freebsd.org/ports'>FreeBSD ports collection</ulink> or <ulink url='http://fink.sf.org/'>fink</ulink> in that it automates the process of building 3rd party software for Mac OS X (and other operating systems).  It also tracks all dependency information for a given piece of software. In other words, it knows what it needs to build and install and in what order for the piece of software you want to work properly. Darwinports knows how to make it build and install it to a specific location, meaning that software installed via DarwinPorts doesn't simply scatter itself all over the system or require user knowledge of what to install in what order.
40                </para>
41               
42                <para>FreeBSD Ports is a large collection of software ported to run on FreeBSD, the ports collection is also used on the other 'Free' BSDs. FreeBSD Ports is based on a large tree of ports where each piece of software has a directory withing a category (like mail or graphics). That directory contains the information needed to build the piece of software. DarwinPorts also uses a directory structure like this, although unlike FreeBSD ports the intention is to not require a complete copy of the 'Ports Tree' on every users machine.  FreeBSD ports is essentially implemented as some very impressive but hairy BSD make(1)'s macros and can be  opaque and non-extensible from the perspective of someone looking to extend or re-factor parts of the system.  Given that Makefiles aren't the easiest thing to parse, or for non-developers to understand, it is also harder to "mine" the FreeBSD ports collection for data to use for other purposes, such as generating documentation indexes or arbitrary front-ends for creating or managing ports.
43                </para>
44               
45                <para>Even discounting some of the limitations of FreeBSD ports described above, the "science" of creating automated build systems is rather more complex than it looks at first glance and there's always room for fresh approaches to the problem, which is what we set out to do with DarwinPorts. There are certainly other systems, some of which have already been mentioned, which have made their own attempts at solving this problem and there will likely be many more such systems in the future since trying to find a single solution which pleases everyone is rather like trying to find a single programming language which pleases everyone - it's more or less impossible.
46                </para>
47               
48                <para>DarwinPorts has been written in Tcl with some components having been written in C. Tcl was chosen to allow DarwinPorts to be readily embeded in other applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read Portfiles.
49                </para>
50               
51                <para>Even though DarwinPorts is written in Tcl, a user also does not need to know Tcl in order to use the system or even to add new ports.  Port description files, though they are actually full Tcl programs in their own right, are designed to look like nothing more than a list of key/value pairs.
52                </para>
53        </sect1>
54       
55       
56        <sect1 id='setup'>
57                <title>Installing Darwinports</title>
58               
59                <sect2 id='prerequisites'>
60                        <title>What you need</title>
61                       
62                        <para>Currently the only officially supported system is Mac OS X 10.2 or later, DarwinPorts will work on FreeBSD and NetBSD most of the time, however those platforms are not as well tested, users of the *BSDs should be able to get DarwinPorts working fairly easily based on these instructions.</para>
63
64                        <para>To install and use DarwinPorts you must install the Developer tools (gcc, autoconf etc on other platforms). All the other prerequisites are pre-installed on Mac OS X 10.2 and later. On other platforms you will need to ensure you have installed Tcl (8.3 or later).
65                        </para>
66                       
67                </sect2>
68               
69                <sect2 id='getting_dports'>
70                        <title>Obtaining DarwinPorts</title>   
71                       
72                        <para>Currently the only way to get DarwinPorts is by using the Concurrent Versioning System (cvs). CVS is installed with the Developers Tools on Mac OS X. To download DarwinPorts using cvs you should use the following Terminal commands. At this time you must keep the darwinports directoy that is downloaded on your machine, even after installation as it also contains all the port description files (Portfiles). In the future these will be automatically downloaded as they are needed so you won't need to keep the directory. Choose a location for darwinports where you won't want/need to move it. For the rest of the document I will assume the user name is 'mike' and the darwinports infrastructure is going to be downloaded to a directory (folder) called darwinports in your home directory (i.e. /Users/mike/darwinports/) you should replace the username with your own username and edit the commands I give so they work correctly on your installation. <programlisting><![CDATA[
73 
74% cd ~/
75% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od login
76% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od co -P darwinports
77]]>
78                                </programlisting>
79                        </para> 
80                       
81                        <para>These commands first ensure you are currently in your home directory, then log onto the opendarwin cvs server and finally 'checkout' (download) DarwinPorts.
82                        </para>
83                       
84                        <para>In the near future we will provide a binary installer for DarwinPorts and the source files downloadable directly from the website rather than requiring users to use cvs. CVS is likely to remain important for users who want to closely track the latest ports as it can be used to update your port descriptions (and is currently the only way to do so).
85                        </para>
86                       
87                </sect2>
88               
89                <sect2 id='install_dports'>
90                        <title>Installing DarwinPorts</title>
91                       
92                        <para>To install DarwinPorts execute the following commands from the darwinports/base directory.<programlisting><![CDATA[
93
94% ./configure
95% make
96% sudo make install
97
98]]>
99                        </programlisting>
100                        This will compile and install all the necessary software. In order to install DarwinPorts on *BSD the default group-ownership must be passed to each make command: <userinput>make DSTGRP=wheel</userinput>.
101                        </para>
102                       
103                        <para>To configure DarwinPorts you should edit /etc/ports/sources.conf. The sources.conf lists the location of both local and remote port software hierarchies (Currently there is not a remote repository). Add an entry for your local ports tree: <userinput>file://Users/mike/darwinports/dports</userinput>. To edit the file you must use a command line text editor like pico or vi.
104                        </para>
105                       
106                        <para>You should add /opt/local/bin (or wherever you chose to install DarwinPorts) to your path. If you aren't sure how, add <userinput>set path=($path /opt/local/bin)</userinput> to your .cshrc file. You may need to create the file first if you haven't set one up before. Then close the Terminal window and open a new one so the new path setting takes effect.
107                        </para>
108                       
109                        <para>Once you have got this far, you should have a working installation of DarwinPorts, you have installed the 'port' command (by default this installed as /opt/local/bin/port) and the libraries it needs (in /opt/local/share/darwinports and /System/Library/Tcl/8.3/darwinports1.0 by default.
110                        </para>
111                       
112                </sect2>
113        </sect1>
114       
115       
116        <sect1>
117                <title>Using DarwinPorts</title>
118               
119                <sect2 id='port'>
120                        <title>port Command</title>
121                       
122                        <para>Using DarwinPorts is very straightforward, most of the time all you need to do is execute a single command to install a port. For example, if you want to install the text editor vile, you'd simply execute the command <userinput>sudo port install vile</userinput>. That will fetch, build and install vim and anything else vim needs to work. All of the examples below use the vim port as an example, you should use whatever port you actually want to install.
123                        </para>
124                       
125                        <para>If you aren't sure of the exact name of your port you can use the search feature. For example, if you wanted to find out if there was anything called vile in the ports you could do: <userinput>port search 'vile'</userinput>. The search facility uses standard regular expression syntax, so you can list all the ports by doing: <userinput>port search '.+'</userinput>.
126                        </para>
127                       
128                        <para>You can see more detail of what is happening when you install a port by using the verbose (-v), or debug (-d) flags when using the port install command, to see all the possible output use them both together: <userinput>port -v -d install vile</userinput>.                   
129                        </para>
130                       
131                        <para>You may break up the installation of a port into a number of steps, fetch, checksum, configure, build, and finally install. Each of these steps performs a part of the process to install a port, using the steps individually is however not normally needed unless you are developing a new port or are trying to diagnose a problem.
132                        </para>
133                       
134                        <para>Once the port has been installed, you may want to delete all the intermediate files that Darwinports has created while building the port, to do this you should enter: <userinput>port clean vile</userinput>.
135                        </para>
136                       
137                        <para>For more information you should look at the port manpage by entering: <userinput>man port</userinput>.
138                        </para>
139                       
140                </sect2>
141               
142                <sect2 id='portindex'>
143                        <title>portindex Command</title>
144                       
145                        <para>Most of the time you won't need to use this command as it is used to build the index of all the available ports, but sometimes the index you have is out of date or innacurate for some reason. When this occurs you will get an error message like 'port search failed: expected integer but got "PortIndex"'. You can fix problem by moving to the dports directory (/Users/mike/darwinports/dports in our examples) and executing: <userinput>portindex</userinput>. This will go through all the available ports in the dport directory and build an index file called PortIndex.
146                        </para>
147                       
148                </sect2>
149               
150                <sect2  id='updating_dports'>
151                        <title>Updating DarwinPorts</title>
152                       
153                        <para>New ports are always being added to the darwinports dports tree, you should regularly update your tree to get access to new ports, and (hopefully) improved versions of current ports. Currently the simplest way you can update the dports tree is to use cvs. You should change directory to the dports directory and then execute: <userinput>cvs -z3 update -dP</userinput>. You should see a set of lines printed out in the terminal as the update progresses. You may need to update your PortIndex as mentioned previously: <userinput>portindex</userinput>.
154                        </para>
155                       
156                        <para>You can also use cvs to fetch an new version of the DarwinPorts infrastructure (eg the port command and associated libraries). To do this you should change directories to the darwinports/base directory and execute the following commands:<programlisting><![CDATA[
157 
158% cvs -z3 update -dP
159% ./configure
160% make clean && make
161% sudo make install
162]]>
163                                </programlisting>This will build and install the new version of DarwinPorts. You don't need to do this very often, although DarwinPorts is a young project and continually improving so we encourage you to keep up to date.
164                        </para>
165                       
166                </sect2>
167               
168                <sect2 id='uninstall_dports'>
169                        <title>Removing Ports</title>
170                       
171                        <para>Ports are removed using the port command described above, simply execute the command: <userinput>sudo port uninstall vile</userinput></para>
172
173                </sect2>
174               
175                <sect2 id='upgrade_dports'>
176                        <title>Upgrading Ports</title>
177                       
178                        <para>At the moment there is not a 'port upgrade' command so to upgrade a port you must uninstall and then install it again. <programlisting><![CDATA[
179 
180% sudo port uninstall vile
181% sudo port install vile
182]]>
183                                </programlisting>
184                        </para>
185                       
186                </sect2>
187        </sect1>
188       
189       
190        <sect1 id='troubleshooting_use'>
191                <title>Troubleshooting</title>
192               
193                <para>There are a number of common problems so before you report a problem (details on how to <link linkend='user_bugs'>report problems</link> follow) check that the problem is described here, or in the <ulink url='http://www.opendarwin.org/projects/darwinports/en/faq.php'>FAQ</ulink> first.
194                </para>
195               
196                <sect2 id='E_port_search'>
197                        <title>port search failed: expected integer but got "PortIndex"</title>
198
199                        <para>This means your PortIndex file is incorrect or potentially corrupted, run the <link linkend='portindex'>portindex</link> command
200                        </para>
201                       
202                </sect2>
203        </sect1>
204       
205       
206        <sect1 id='portsmanager'>
207                <title>Ports Manager.app</title>
208               
209                <para>Ports Manager.app is a Cocoa GUI for the DarwinPorts project, it allows users to browse through available ports and there descriptions and to download, install and uninstall the software. Ports Manager.app is currently under development and is less reliable in use than the command line tools. There is a Port for the application so you can actually use Darwinports to install it for you! <userinput>sudo port install 'PortsManager'</userinput>. Ports Manager.app will be installed in your /Applications/Utilities folder.
210                </para>
211               
212                <para>We will also be providing a binary installer (a '.pkg') file in the near future for Ports Manager.app.
213                </para>
214               
215        </sect1>
216</chapter>
Note: See TracBrowser for help on using the repository browser.