[73017] trunk/doc-new/guide/xml
mk at macports.org
mk at macports.org
Mon Nov 1 03:39:01 PDT 2010
Revision: 73017
http://trac.macports.org/changeset/73017
Author: mk at macports.org
Date: 2010-11-01 03:38:58 -0700 (Mon, 01 Nov 2010)
Log Message:
-----------
guide: resurrect PortGroup gnustep's previous revision and modify intro according to Ryan's explanations received by email on Nov. 1st
Modified Paths:
--------------
trunk/doc-new/guide/xml/portgroup-gnustep.xml
trunk/doc-new/guide/xml/portgroups.xml
trunk/doc-new/guide/xml/using.xml
Modified: trunk/doc-new/guide/xml/portgroup-gnustep.xml
===================================================================
--- trunk/doc-new/guide/xml/portgroup-gnustep.xml 2010-11-01 10:00:26 UTC (rev 73016)
+++ trunk/doc-new/guide/xml/portgroup-gnustep.xml 2010-11-01 10:38:58 UTC (rev 73017)
@@ -6,7 +6,10 @@
<title>PortGroup gnustep</title>
<para>PortGroup gnustep allows for efficient porting of GNUstep-based open
- source software.</para>
+ source software using the GNU objective-C runtime that defines options for
+ the configuration, build, and destroot phases, and also defines some
+ values for GNUstep-based software. A minimum Portfile using the gnustep
+ PortGroup class need only define the fetch and the checksum phases.</para>
<section id="reference.portgroup.gnustep.portgroup-keywords">
<title>gnustep PortGroup Specific Keywords</title>
Modified: trunk/doc-new/guide/xml/portgroups.xml
===================================================================
--- trunk/doc-new/guide/xml/portgroups.xml 2010-11-01 10:00:26 UTC (rev 73016)
+++ trunk/doc-new/guide/xml/portgroups.xml 2010-11-01 10:38:58 UTC (rev 73017)
@@ -5,12 +5,15 @@
<title>PortGroup introduction</title>
- <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>
-
- <para>See the following folder for currently defined port groups:</para>
+ <para>PortGroups are simply include files for portfiles. They can define as much or as little as
+ a portgroup author feels is necessary to provide a set of definitions or behaviors common to a
+ group of portfiles, in order that those portfiles can be expressed as simply as possible with
+ minimum redundancy.</para>
+
+<para>See the following folder for PortGroup definitions:</para>
<filename>${prefix}/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/</filename>
- <para>This folder contains various tcl files which are describing all port groups. It follows an examplary (incomplete) listing:</para>
+ <para>A sample listing follows:</para>
<programlisting><prompt>%%</prompt> <userinput>ls -1 /opt/local/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/</userinput></programlisting>
@@ -27,5 +30,10 @@
.
.</screen>
-
+ <para>The requirements of a minimum portfile using a portgroup varies by portgroup.
+ The sections below devoted to each portgroup (or, for portgroups not documented there yet, the
+ comments in the header of the portgroup file itself) should provide guidance on how each
+ portgroup is used. Prospective MacPorts developers are also encouraged to examine existing
+ portfiles that use these portgroups.</para>
+
</section>
Modified: trunk/doc-new/guide/xml/using.xml
===================================================================
--- trunk/doc-new/guide/xml/using.xml 2010-11-01 10:00:26 UTC (rev 73016)
+++ trunk/doc-new/guide/xml/using.xml 2010-11-01 10:38:58 UTC (rev 73017)
@@ -433,9 +433,264 @@
<title>Common Tasks</title>
<para>This section lists common operations you may want to perform when
- managing a MacPorts installation.</para>
+ managing a MacPorts installation. It might be a bit repetitive, because some commands are
+ already described somewhere else in this guide, but will give an overview of a typical
+ maintenance workflow.</para>
- <para>TODO: Add content here.</para>
+ <variablelist>
+
+ <varlistentry>
+ <term>Updating your ports tree</term>
+
+ <listitem>
+ <para>is an essential to stay up-to-date with MacPorts (Mind the 'sudo' for
+ some of the subsequent examples, which is necessary if you have a system-wide MacPorts installation.):</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
+
+ <screen>Password:
+---> Updating the ports tree
+---> Updating MacPorts base sources using rsync
+MacPorts base version 1.9.1 installed,
+MacPorts base version 1.9.1 downloaded.
+---> MacPorts base is already the latest version
+
+The ports tree has been updated. To upgrade your installed ports, you should run
+ port upgrade outdated</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Show all ports which actually need updating</term>
+
+ <listitem>
+ <para>is often useful, in case you don't have time to wait for port upgrades
+ (Every port needs to be downloaded, configured, build and installed, which can be -
+ depending on your systems resources - a very time consuming procedure.):</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
+ <screen>The following installed ports are outdated:
+makedepend 1.0.2_0 < 1.0.3_0
+Xft2 2.1.14_0 < 2.2.0_0
+xorg-bigreqsproto 1.1.0_0 < 1.1.1_0
+xorg-compositeproto 0.4.1_0 < 0.4.2_0
+xorg-damageproto 1.2.0_0 < 1.2.1_0
+xorg-fixesproto 4.1.1_0 < 4.1.2_0
+xorg-libXdmcp 1.0.3_0 < 1.1.0_0
+xorg-libXmu 1.0.5_0 < 1.1.0_0
+xorg-libXScrnSaver 1.2.0_0 < 1.2.1_0
+xorg-randrproto 1.3.1_0 < 1.3.2_0
+xorg-scrnsaverproto 1.2.0_0 < 1.2.1_0
+xorg-xcmiscproto 1.2.0_0 < 1.2.1_0
+xpm 3.5.8_0 < 3.5.9_0
+xorg-util-macros 1.10.1_0 < 1.11.0_0</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Upgrade a certain port</term>
+
+ <listitem>
+ <para>e.g. in case you don't have enough time to upgrade your whole MacPorts tree:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
+ <screen>Password:
+---> Computing dependencies for makedepend
+---> Fetching makedepend
+---> Attempting to fetch makedepend-1.0.3.tar.bz2 from http://lil.fr.distfiles.macports.org/makedepend
+---> Verifying checksum(s) for makedepend
+---> Extracting makedepend
+---> Configuring makedepend
+---> Building makedepend
+---> Staging makedepend into destroot
+---> Computing dependencies for makedepend
+---> Installing makedepend @1.0.3_0
+---> Deactivating makedepend @1.0.2_0
+---> Activating makedepend @1.0.3_0
+---> Cleaning makedepend</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Removing inactive version(s) of upgraded port(s)</term>
+
+ <listitem>
+ <para>makes sense if you are sure that you won't change back to the older version(s)
+ (which could be necessary in case of newly introduced bugs in the upgraded port version):</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
+ <screen>The following ports are currently installed:
+ makedepend @1.0.2_0</screen>
+
+ <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
+ <screen>Password:
+---> Uninstalling makedepend @1.0.2_0</screen>
+
+ <para>Of course one could also select only a specific inactive port,
+ but that requires to specify the exact version:</para>
+ <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
+ <screen>Password:
+---> Uninstalling makedepend @1.0.2_0</screen>
+
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>Finding ports depending on a certain port</term>
+
+ <listitem>
+ <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
+
+ <screen>mkfontscale
+xorg-libAppleWM
+xorg-libX11
+xorg-libXaw
+xorg-libXevie
+xorg-libXp
+xorg-libXt
+xorg-server
+xorg-server-devel
+xscope
+xtrap</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Finding ports which are leaves</term>
+
+ <listitem>
+ <para>can be sometimes worthwhile, since often additional ports get installed when
+ a specific port is installed. One can imagine that if one keeps installing and
+ uninstalling ports for some time the MacPorts tree can be swamped with ports actually
+ not necessary anymore. Ports not being a dependency for any other port are called leaves
+ and can be found issuing the command:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
+ <screen>aalib @1.4rc5_4
+autoconf @2.68_0
+autoconf263 @2.63_0
+automake @1.11.1_0
+cmake @2.8.2_4
+coreutils @8.5_0</screen>
+
+ <para>The following command delivers a similar result, but works much slower (due to additional parsing):</para>
+ <programlisting><prompt>%%</prompt> <userinput>port list leaves</userinput></programlisting>
+ <screen>aalib @1.4rc5 graphics/aalib
+autoconf @2.68 devel/autoconf
+autoconf263 @2.63 devel/autoconf263
+automake @1.11.1 devel/automake
+cmake @2.8.2 devel/cmake
+coreutils @8.5 sysutils/coreutils</screen>
+
+ <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Define a port as requested (being a rather lengthy usage example)</term>
+
+ <listitem>
+ <note>
+ <para>This is a feature introduced with MacPorts version 1.9 and it is in fact
+ necessary to dedicate a seperate subsection to it somewhere in the section covering
+ all port commands.</para>
+ </note>
+
+ <para>Defining a port as a requested port makes maintenance of the MacPorts tree
+ much easier, since the maintainer can, for instance, now more easily spot leftovers
+ (i.e. leaves) of previous installation orgies.:</para>
+
+ <para>Well, before we come to the procedure of defining your requested ports,
+ let's have a look at a typical scenario when you want to understand what is
+ actually installed and what is on other hand truely necessary for your system.
+ Say checking leaves on the MacPorts tree gives this output:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
+ <screen>aalib @1.4rc5_4
+autoconf @2.68_0
+autoconf263 @2.63_0
+automake @1.11.1_0
+cmake @2.8.2_4
+coreutils @8.5_0
+physfs @2.0.1_0</screen>
+
+ <para>Now it is up to the maintainer to decide what's needed and what is not.
+ Let's say one certainly would want ports starting with autoconf up to coreutils,
+ since they are often used in port installation. Set those as requested ports using:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
+
+ <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
+ know what to make of it, you need to check out what it actually is and which ports needed
+ its installation at some time in the past.</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
+ <screen>physfs @2.0.1 (devel)
+Variants: debug, universal
+
+Description: PhysicsFS is a library to provide abstract access to various
+ archives. It is intended for use in video games, and the design
+ was somewhat inspired by Quake 3's file subsystem.
+Homepage: http://icculus.org/physfs/
+
+Build Dependencies: cmake
+Library Dependencies: zlib
+Platforms: darwin
+License: unknown
+Maintainers: nomaintainer at macports.org</screen>
+
+ <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
+ find out which ports actually depend on it, perhaps that might ring a bell:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
+ <screen>fbg
+libsdl_sound
+lincity-ng
+netpanzer</screen>
+
+ <para>No, you didn't install netpanzer either,
+ but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
+ unfortunately that port was broken (see issue <ulink url="http://trac.macports.org/ticket/24641">#24641</ulink>) when
+ you were trying to install it... Before you ran into the issue, of course, fbg's dependencies
+ were resolved by MacPorts, which is why port physfs is still present on your system.
+ Uff, great, confusion resolved. :-)</para>
+
+ <para>When you've step-by-step figured out which ports you want to keep on your system and
+ have set them as requested, you'll have a list of unnecessary ports, which might be
+ eventually as short as this:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
+ <screen>aalib @1.4rc5_4
+physfs @2.0.1_0 </screen>
+
+ <para>Get rid of them by issuing the command:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port uninstall leaves</userinput></programlisting>
+ <screen>---> Deactivating physfs @2.0.1_0
+---> Cleaning physfs
+---> Uninstalling physfs @2.0.1_0
+---> Cleaning physfs
+---> Deactivating aalib @1.4rc5_4
+---> Uninstalling aalib @1.4rc5_4</screen>
+
+ <para>Find all installed ports you previously set as requested using:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
+
+ <para>Checking the list of leaves from time to time will help to keep your system
+ free of too much "garbage". However, keep in mind that some ports may be dependencies
+ only during the installation of a port (library dependencies, installation or
+ configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
+ otherwise you'll see them being installed again and again.</para>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
</section>
<section id="using.binaries">
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macports-changes/attachments/20101101/e450c215/attachment.html>
More information about the macports-changes
mailing list