source: trunk/doc/guide/xml/user/portimages.xml @ 7634

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

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

Documentation for Users about Port Images.

  • Property svn:eol-style set to native
File size: 6.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="portimages">
5  <chapterinfo>
6    <keywordset>
7      <keyword>
8                                images
9      </keyword>
10    </keywordset>
11  </chapterinfo>
12 
13  <title>DarwinPorts Port Images</title> 
14 
15  <sect1>
16    <title>About this chapter</title>
17
18                <para>This chapter provides an overview of the DarwinPorts Port
19                        Image model of installing and using ports for users of
20                        DarwinPorts.  A more complete overview of Port Images can be found
21                        in the DarwinPorts Internals part of this Guide.</para>
22  </sect1>
23       
24  <sect1 id='what'>
25    <title>What Are Port Images?</title>
26   
27                <para>Port Images are a new model for installing and using your
28                        ported software.  At the most basic level, Port Images are a
29                        solution to the problem of needing or wanting multiple different
30                        versions, revisions, and/or variants of the same port installed at
31                        the same time.  This is accomplished by installing the port into a
32                        repository location and then create links, or aliases, from that
33                        repository location into the <varname>${prefix}</varname> from
34                        where you can use the DarwinPorts ports.</para>
35
36                <para>Port Images provide the ability to test new versions of a
37                        port, or different variants of a port, without having to uninstall
38                        a previous and/or working version of that port.  This is
39                        accomplished using one of the key concepts of Images:
40                        <emphasis>activation</emphasis>.</para>
41  </sect1>
42        <sect1 id="activation">
43                <title>Port Image Activation</title>
44
45                <para>With Port Images in DarwinPorts, the port is installed as an
46                        <emphasis>image</emphasis> to the DarwinPorts <emphasis>image
47                        repository</emphasis>.  This repository can be thought of as an
48                        library of ports that actually contains all of the files belonging
49                        to that port.  Once the port is installed as an image, the port
50                        can be <emphasis>activated</emphasis>.</para>
51                       
52                <para>Activation simply creates the links into the
53                        <varname>${prefix}</varname> of DarwinPorts.  DarwinPorts manages
54                        any conflicts between any ports that are activated, and will
55                        inform you if one port is attempting to link a file that already
56                        exists and belongs to another port.  You have the option to force
57                        DarwinPorts to go ahead and activate the port in the event of a
58                        conflict, and DarwinPorts will continue, moving the old file out
59                        of the way.</para>
60
61                <para>By default, DarwinPorts will go ahead and activate a port when
62                        you run <userinput>port install vim</userinput>.  Once a port is
63                        installed and activated, you can <emphasis>deactivate</emphasis>,
64                        in addition to <emphasis>uninstalling</emphasis> it.  If you wish
65                        to move one port out of the way of another port or another variant
66                        or version of the same port, you can <emphasis>deactivate
67                        it</emphasis>.  When you do this, the port is still installed in
68                        the <emphasis>image repository</emphasis>, but simply not linked
69                        into <varname>${prefix}</varname>.</para>
70        </sect1>
71       
72        <sect1 id="using_images">
73                <title>Using Port Images</title>
74
75                <para>DarwinPorts uses Port Images by default now, so if you are
76                        using a recent release of DarwinPorts, you are using Port Images!
77                        Port Images will work transparently for users used to the old
78                        installation model of DarwinPorts, as well as those familiar with
79                        other port systems.  If you wish to use the advanced features that
80                        Port Images provide, namely activation and deactivation, the
81                        following commands are available:</para>
82
83                <variablelist>
84                        <varlistentry>
85                                <term><userinput>port installed vim</userinput></term>
86                                       
87                                <listitem>
88                                        <para>This command will list all installed versions and
89                                        variants of the <varname>vim</varname> port.  You can use this
90                                        command to find the version string the port if you have
91                                        multiple versions installed and wish to activate or deactivate
92                                        one version.</para>
93                                </listitem>
94                        </varlistentry>
95                        <varlistentry>
96                                <term><userinput>port activate vim</userinput></term>
97                                       
98                                <listitem>
99                                        <para>This command will activate the <varname>vim</varname>
100                                        port.  If there are multiple versions of the
101                                        <varname>vim</varname> port installed, you will need to
102                                        provide the version string of the port you wish to
103                                        activate.</para>
104                                </listitem>
105                        </varlistentry>
106                        <varlistentry>
107                                <term><userinput>port activate vim 6.2.532+gtk2</userinput></term>
108                                       
109                                <listitem>
110                                        <para>This command will activate the specific version of the
111                                        <varname>vim</varname> given using the version string.  This
112                                        is how you activate one version of a port out of two or more
113                                        installed versions of that port.</para>
114                                </listitem>
115                        </varlistentry>
116                        <varlistentry>
117                                <term><userinput>port deactivate vim</userinput></term>
118                                       
119                                <listitem>
120                                        <para>This command will deactivate the <varname>vim</varname>
121                                        port.  If there are multiple versions of the
122                                        <varname>vim</varname> port installed, you will need to
123                                        provide the version string of the port you wish to
124                                        deactivate.</para>
125                                </listitem>
126                        </varlistentry>
127                        <varlistentry>
128                                <term><userinput>port deactivate vim 6.2.532+gtk2</userinput></term>
129                                       
130                                <listitem>
131                                        <para>This command will deactivate the specific version of the
132                                        <varname>vim</varname> given using the version string.  This
133                                        is how you deactivate one version of a port out of two or more
134                                        installed versions of that port.</para>
135                                </listitem>
136                        </varlistentry>
137                        <varlistentry>
138                                <term><userinput>port location vim</userinput></term>
139                                       
140                                <listitem>
141                                        <para>This command will simply give you the full path to the
142                                        image location where the <varname>vim</varname> port is
143                                        installed.  If you have more than one version or variants of a
144                                        single port installed, you can specify the version string of
145                                        the port as the last argument, similar to the above examples
146                                        of activation and deactivation.</para>
147                                </listitem>
148                        </varlistentry>
149                </variablelist>
150        </sect1>
151</chapter>
Note: See TracBrowser for help on using the repository browser.