Changeset 73017 for trunk/doc-new


Ignore:
Timestamp:
Nov 1, 2010, 10:38:58 AM (9 years ago)
Author:
mk@…
Message:

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

Location:
trunk/doc-new/guide/xml
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/guide/xml/portgroup-gnustep.xml

    r72889 r73017  
    77
    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>
    1013
    1114  <section id="reference.portgroup.gnustep.portgroup-keywords">
  • trunk/doc-new/guide/xml/portgroups.xml

    r72888 r73017  
    66  <title>PortGroup introduction</title>
    77
    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>
    9  
    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>
     12
     13<para>See the following folder for PortGroup definitions:</para>
    1114  <filename>${prefix}/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/</filename>
    1215
    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>
    1417
    1518    <programlisting><prompt>%%</prompt> <userinput>ls -1 /opt/local/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/</userinput></programlisting>
     
    2831.</screen>
    2932
    30 
     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>
     38   
    3139</section>
  • trunk/doc-new/guide/xml/using.xml

    r70151 r73017  
    434434
    435435    <para>This section lists common operations you may want to perform when
    436     managing a MacPorts installation.</para>
    437 
    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>
     439
     440    <variablelist>
     441
     442      <varlistentry>
     443        <term>Updating your ports tree</term>
     444
     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>
     448
     449          <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
     450
     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
     457
     458The ports tree has been updated. To upgrade your installed ports, you should run
     459  port upgrade outdated</screen>
     460        </listitem>
     461      </varlistentry>
     462
     463      <varlistentry>
     464        <term>Show all ports which actually need updating</term>
     465
     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>
     470
     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>
     489
     490      <varlistentry>
     491        <term>Upgrade a certain port</term>
     492
     493        <listitem>
     494          <para>e.g. in case you don't have enough time to upgrade your whole MacPorts tree:</para>
     495
     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 http://lil.fr.distfiles.macports.org/makedepend
     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>
     513
     514      <varlistentry>
     515        <term>Removing inactive version(s) of upgraded port(s)</term>
     516
     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>
     520
     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>
     524 
     525          <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
     526          <screen>Password:
     527--->  Uninstalling makedepend @1.0.2_0</screen>
     528
     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>
     534
     535        </listitem>
     536      </varlistentry>
     537
     538
     539      <varlistentry>
     540        <term>Finding ports depending on a certain port</term>
     541
     542        <listitem>
     543          <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
     544
     545          <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
     546
     547          <screen>mkfontscale
     548xorg-libAppleWM
     549xorg-libX11
     550xorg-libXaw
     551xorg-libXevie
     552xorg-libXp
     553xorg-libXt
     554xorg-server
     555xorg-server-devel
     556xscope
     557xtrap</screen>
     558        </listitem>
     559      </varlistentry>
     560
     561      <varlistentry>
     562        <term>Finding ports which are leaves</term>
     563
     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>
     570
     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>
     578
     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>
     587
     588          <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
     589        </listitem>
     590      </varlistentry>
     591
     592      <varlistentry>
     593        <term>Define a port as requested (being a rather lengthy usage example)</term>
     594
     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>
     601         
     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>
     605
     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>
     610
     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>
     619
     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>
     623
     624          <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
     625
     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>
     629
     630          <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
     631          <screen>physfs @2.0.1 (devel)
     632Variants:             debug, universal
     633
     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.
     637Homepage:             http://icculus.org/physfs/
     638
     639Build Dependencies:   cmake
     640Library Dependencies: zlib
     641Platforms:            darwin
     642License:              unknown
     643Maintainers:          nomaintainer@macports.org</screen>
     644
     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>
     647
     648          <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
     649          <screen>fbg                             
     650libsdl_sound                   
     651lincity-ng                     
     652netpanzer</screen>
     653
     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="http://trac.macports.org/ticket/24641">#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>
     660
     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>
     664
     665          <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     666          <screen>aalib                          @1.4rc5_4
     667physfs                         @2.0.1_0 </screen>
     668
     669          <para>Get rid of them by issuing the command:</para>
     670
     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>
     678
     679          <para>Find all installed ports you previously set as requested using:</para>
     680
     681          <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
     682
     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>
     688
     689        </listitem>
     690      </varlistentry>
     691
     692    </variablelist>
     693
    439694  </section>
    440695
Note: See TracChangeset for help on using the changeset viewer.