Changeset 73017 for trunk/doc-new

Nov 1, 2010, 10:38:58 AM (9 years ago)

guide: resurrect PortGroup gnustep's previous revision and modify intro according to Ryan's explanations received by email on Nov. 1st

3 edited


  • trunk/doc-new/guide/xml/portgroup-gnustep.xml

    r72889 r73017  
    88  <para>PortGroup gnustep allows for efficient porting of GNUstep-based open
    9   source software.</para>
     9  source software using the GNU objective-C runtime that defines options for
     10  the configuration, build, and destroot phases, and also defines some
     11  values for GNUstep-based software. A minimum Portfile using the gnustep
     12  PortGroup class need only define the fetch and the checksum phases.</para>
    1114  <section id="reference.portgroup.gnustep.portgroup-keywords">
  • trunk/doc-new/guide/xml/portgroups.xml

    r72888 r73017  
    66  <title>PortGroup introduction</title>
    8   <para>Port groups allow for efficient porting of open source software using the GNU objective-C runtime that defines options for the configuration, build, and destroot phases, and also defines some values for a specific software. A minimum Portfile using a PortGroup class needs to only define the fetch and the checksum phases.</para>
    10   <para>See the following folder for currently defined port groups:</para>
     8  <para>PortGroups are simply include files for portfiles. They can define as much or as little as
     9  a portgroup author feels is necessary to provide a set of definitions or behaviors common to a
     10  group of portfiles, in order that those portfiles can be expressed as simply as possible with
     11  minimum redundancy.</para>
     13<para>See the following folder for PortGroup definitions:</para>
    1114  <filename>${prefix}/var/macports/sources/</filename>
    13   <para>This folder contains various tcl files which are describing all port groups. It follows an examplary (incomplete) listing:</para>
     16  <para>A sample listing follows:</para>
    1518    <programlisting><prompt>%%</prompt> <userinput>ls -1 /opt/local/var/macports/sources/</userinput></programlisting>
     33   <para>The requirements of a minimum portfile using a portgroup varies by portgroup.
     34   The sections below devoted to each portgroup (or, for portgroups not documented there yet, the
     35   comments in the header of the portgroup file itself) should provide guidance on how each
     36   portgroup is used. Prospective MacPorts developers are also encouraged to examine existing
     37   portfiles that use these portgroups.</para>
  • trunk/doc-new/guide/xml/using.xml

    r70151 r73017  
    435435    <para>This section lists common operations you may want to perform when
    436     managing a MacPorts installation.</para>
    438     <para>TODO: Add content here.</para>
     436    managing a MacPorts installation. It might be a bit repetitive, because some commands are
     437    already described somewhere else in this guide, but will give an overview of a typical
     438    maintenance workflow.</para>
     440    <variablelist>
     442      <varlistentry>
     443        <term>Updating your ports tree</term>
     445        <listitem>
     446          <para>is an essential to stay up-to-date with MacPorts (Mind the 'sudo' for
     447          some of the subsequent examples, which is necessary if you have a system-wide MacPorts installation.):</para>
     449          <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
     451          <screen>Password:
     452--->  Updating the ports tree
     453--->  Updating MacPorts base sources using rsync
     454MacPorts base version 1.9.1 installed,
     455MacPorts base version 1.9.1 downloaded.
     456--->  MacPorts base is already the latest version
     458The ports tree has been updated. To upgrade your installed ports, you should run
     459  port upgrade outdated</screen>
     460        </listitem>
     461      </varlistentry>
     463      <varlistentry>
     464        <term>Show all ports which actually need updating</term>
     466        <listitem>
     467          <para>is often useful, in case you don't have time to wait for port upgrades
     468          (Every port needs to be downloaded, configured, build and installed, which can be -
     469          depending on your systems resources - a very time consuming procedure.):</para>
     471          <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
     472          <screen>The following installed ports are outdated:
     473makedepend                     1.0.2_0 &lt; 1.0.3_0         
     474Xft2                           2.1.14_0 &lt; 2.2.0_0       
     475xorg-bigreqsproto              1.1.0_0 &lt; 1.1.1_0         
     476xorg-compositeproto            0.4.1_0 &lt; 0.4.2_0         
     477xorg-damageproto               1.2.0_0 &lt; 1.2.1_0         
     478xorg-fixesproto                4.1.1_0 &lt; 4.1.2_0         
     479xorg-libXdmcp                  1.0.3_0 &lt; 1.1.0_0         
     480xorg-libXmu                    1.0.5_0 &lt; 1.1.0_0         
     481xorg-libXScrnSaver             1.2.0_0 &lt; 1.2.1_0         
     482xorg-randrproto                1.3.1_0 &lt; 1.3.2_0         
     483xorg-scrnsaverproto            1.2.0_0 &lt; 1.2.1_0         
     484xorg-xcmiscproto               1.2.0_0 &lt; 1.2.1_0         
     485xpm                            3.5.8_0 &lt; 3.5.9_0         
     486xorg-util-macros               1.10.1_0 &lt; 1.11.0_0</screen>
     487        </listitem>
     488      </varlistentry>
     490      <varlistentry>
     491        <term>Upgrade a certain port</term>
     493        <listitem>
     494          <para>e.g. in case you don't have enough time to upgrade your whole MacPorts tree:</para>
     496          <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
     497          <screen>Password:
     498--->  Computing dependencies for makedepend
     499--->  Fetching makedepend
     500--->  Attempting to fetch makedepend-1.0.3.tar.bz2 from
     501--->  Verifying checksum(s) for makedepend
     502--->  Extracting makedepend
     503--->  Configuring makedepend
     504--->  Building makedepend
     505--->  Staging makedepend into destroot
     506--->  Computing dependencies for makedepend
     507--->  Installing makedepend @1.0.3_0
     508--->  Deactivating makedepend @1.0.2_0
     509--->  Activating makedepend @1.0.3_0
     510--->  Cleaning makedepend</screen>
     511        </listitem>
     512      </varlistentry>
     514      <varlistentry>
     515        <term>Removing inactive version(s) of upgraded port(s)</term>
     517        <listitem>
     518          <para>makes sense if you are sure that you won't change back to the older version(s)
     519          (which could be necessary in case of newly introduced bugs in the upgraded port version):</para>
     521          <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
     522          <screen>The following ports are currently installed:
     523  makedepend @1.0.2_0</screen>
     525          <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
     526          <screen>Password:
     527--->  Uninstalling makedepend @1.0.2_0</screen>
     529          <para>Of course one could also select only a specific inactive port,
     530          but that requires to specify the exact version:</para>
     531          <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
     532          <screen>Password:
     533--->  Uninstalling makedepend @1.0.2_0</screen>
     535        </listitem>
     536      </varlistentry>
     539      <varlistentry>
     540        <term>Finding ports depending on a certain port</term>
     542        <listitem>
     543          <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
     545          <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
     547          <screen>mkfontscale
     558        </listitem>
     559      </varlistentry>
     561      <varlistentry>
     562        <term>Finding ports which are leaves</term>
     564        <listitem>
     565          <para>can be sometimes worthwhile, since often additional ports get installed when
     566          a specific port is installed. One can imagine that if one keeps installing and
     567          uninstalling ports for some time the MacPorts tree can be swamped with ports actually
     568          not necessary anymore. Ports not being a dependency for any other port are called leaves
     569          and can be found issuing the command:</para>
     571          <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     572          <screen>aalib                          @1.4rc5_4
     573autoconf                       @2.68_0
     574autoconf263                    @2.63_0
     575automake                       @1.11.1_0
     576cmake                          @2.8.2_4
     577coreutils                      @8.5_0</screen>
     579          <para>The following command delivers a similar result, but works much slower (due to additional parsing):</para>
     580          <programlisting><prompt>%%</prompt> <userinput>port list leaves</userinput></programlisting>
     581          <screen>aalib                          @1.4rc5         graphics/aalib
     582autoconf                       @2.68           devel/autoconf
     583autoconf263                    @2.63           devel/autoconf263
     584automake                       @1.11.1         devel/automake
     585cmake                          @2.8.2          devel/cmake
     586coreutils                      @8.5            sysutils/coreutils</screen>
     588          <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
     589        </listitem>
     590      </varlistentry>
     592      <varlistentry>
     593        <term>Define a port as requested (being a rather lengthy usage example)</term>
     595        <listitem>
     596          <note>
     597            <para>This is a feature introduced with MacPorts version 1.9 and it is in fact
     598            necessary to dedicate a seperate subsection to it somewhere in the section covering
     599            all port commands.</para>
     600          </note>
     602          <para>Defining a port as a requested port makes maintenance of the MacPorts tree
     603          much easier, since the maintainer can, for instance, now more easily spot leftovers
     604          (i.e. leaves) of previous installation orgies.:</para>
     606          <para>Well, before we come to the procedure of defining your requested ports,
     607          let's have a look at a typical scenario when you want to understand what is
     608          actually installed and what is on other hand truely necessary for your system.
     609          Say checking leaves on the MacPorts tree gives this output:</para>
     611          <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     612          <screen>aalib                          @1.4rc5_4
     613autoconf                       @2.68_0
     614autoconf263                    @2.63_0
     615automake                       @1.11.1_0
     616cmake                          @2.8.2_4
     617coreutils                      @8.5_0
     618physfs                         @2.0.1_0</screen>
     620          <para>Now it is up to the maintainer to decide what's needed and what is not.
     621          Let's say one certainly would want ports starting with autoconf up to coreutils,
     622          since they are often used in port installation. Set those as requested ports using:</para>
     624          <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
     626          <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
     627          know what to make of it, you need to check out what it actually is and which ports needed
     628          its installation at some time in the past.</para>
     630          <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
     631          <screen>physfs @2.0.1 (devel)
     632Variants:             debug, universal
     634Description:          PhysicsFS is a library to provide abstract access to various
     635                      archives. It is intended for use in video games, and the design
     636                      was somewhat inspired by Quake 3's file subsystem.
     639Build Dependencies:   cmake
     640Library Dependencies: zlib
     641Platforms:            darwin
     642License:              unknown
     645          <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
     646          find out which ports actually depend on it, perhaps that might ring a bell:</para>
     648          <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
     649          <screen>fbg                             
     654          <para>No, you didn't install netpanzer either,
     655          but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
     656          unfortunately that port was broken (see issue <ulink url="">#24641</ulink>) when
     657          you were trying to install it... Before you ran into the issue, of course, fbg's dependencies
     658          were resolved by MacPorts, which is why port physfs is still present on your system.
     659          Uff, great, confusion resolved. :-)</para>
     661          <para>When you've step-by-step figured out which ports you want to keep on your system and
     662          have set them as requested, you'll have a list of unnecessary ports, which might be
     663          eventually as short as this:</para>
     665          <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     666          <screen>aalib                          @1.4rc5_4
     667physfs                         @2.0.1_0 </screen>
     669          <para>Get rid of them by issuing the command:</para>
     671          <programlisting><prompt>%%</prompt> <userinput>port uninstall leaves</userinput></programlisting>
     672          <screen>--->  Deactivating physfs @2.0.1_0
     673--->  Cleaning physfs
     674--->  Uninstalling physfs @2.0.1_0
     675--->  Cleaning physfs
     676--->  Deactivating aalib @1.4rc5_4
     677--->  Uninstalling aalib @1.4rc5_4</screen>
     679          <para>Find all installed ports you previously set as requested using:</para>
     681          <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
     683          <para>Checking the list of leaves from time to time will help to keep your system
     684          free of too much "garbage". However, keep in mind that some ports may be dependencies
     685          only during the installation of a port (library dependencies, installation or
     686          configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
     687          otherwise you'll see them being installed again and again.</para>
     689        </listitem>
     690      </varlistentry>
     692    </variablelist>
    439694  </section>
Note: See TracChangeset for help on using the changeset viewer.