Changeset 73691 for trunk/doc-new


Ignore:
Timestamp:
Nov 21, 2010, 9:48:38 PM (9 years ago)
Author:
mk@…
Message:

guide: reformat section '3.3 Common Tasks' according to http://trac.macports.org/ticket/27078#comment:3

File:
1 edited

Legend:

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

    r73671 r73691  
    456456    <title>Common Tasks</title>
    457457
    458     <para>This section lists common operations you may want to perform when
    459     managing a MacPorts installation. It might be a bit repetitive, because some commands are
    460     already described somewhere else in this guide, but will give an overview of a typical
    461     maintenance workflow.</para>
     458    <para>This section lists common operations you may want to perform when managing a MacPorts
     459    installation. Some commands are described in further details elsewhere in the guide.</para>
    462460
    463461    <para>Mind the 'sudo' for some of the subsequent examples, which is necessary if you have a
    464     system-wide MacPorts installation.</para>
    465 
    466     <variablelist>
    467 
    468       <varlistentry>
    469         <term>Updating your ports tree</term>
    470 
    471         <listitem>
    472           <para>is essential to stay up-to-date with MacPorts:</para>
    473 
    474           <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
    475 
    476           <screen>Password:
     462    root-MacPorts-installation.</para>
     463
     464    <section id="using.common-tasks.updating">
     465      <title>Updating your ports tree</title>
     466
     467      <para>is essential to stay up-to-date with MacPorts:</para>
     468
     469      <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
     470
     471      <screen>Password:
    477472--->  Updating the ports tree
    478473--->  Updating MacPorts base sources using rsync
     
    483478The ports tree has been updated. To upgrade your installed ports, you should run
    484479  port upgrade outdated</screen>
    485         </listitem>
    486       </varlistentry>
    487 
    488       <varlistentry>
    489         <term>Show all ports which actually need updating</term>
    490 
    491         <listitem>
    492           <para>is often useful, in case you don't have time to wait for port upgrades
     480    </section>
     481
     482    <section id="using.common-tasks.showports">
     483      <title>Show all ports which actually need updating</title>
     484
     485      <para>is often useful, in case you don't have time to wait for port upgrades
    493486          (Every port needs to be downloaded, configured, build and installed, which can be -
    494487          depending on your systems resources - a very time consuming procedure.):</para>
    495488
    496           <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
    497           <screen>The following installed ports are outdated:
     489      <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
     490      <screen>The following installed ports are outdated:
    498491makedepend                     1.0.2_0 &lt; 1.0.3_0         
    499492Xft2                           2.1.14_0 &lt; 2.2.0_0       
     
    510503xpm                            3.5.8_0 &lt; 3.5.9_0         
    511504xorg-util-macros               1.10.1_0 &lt; 1.11.0_0</screen>
    512         </listitem>
    513       </varlistentry>
    514 
    515       <varlistentry>
    516         <term>Upgrading active ports</term>
    517 
    518         <listitem>
    519           <para>is usually done with the follwoing command:</para>
    520 
    521           <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
    522         </listitem>
    523 
    524         <listitem>
    525           <para>In case you want to upgrade only a specific port (for whatever reason):</para>
    526 
    527           <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
    528           <screen>Password:
     505    </section>
     506
     507    <section id="using.common-tasks.upgrading">
     508      <title>Upgrading active ports</title>
     509
     510      <para>is usually done with the follwoing command:</para>
     511
     512      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
     513
     514      <para>In case you want to upgrade only a specific port (for whatever reason):</para>
     515
     516      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
     517      <screen>Password:
    529518--->  Computing dependencies for makedepend
    530519--->  Fetching makedepend
     
    540529--->  Activating makedepend @1.0.3_0
    541530--->  Cleaning makedepend</screen>
    542         </listitem>
    543       </varlistentry>
    544 
    545       <varlistentry>
    546         <term>Removing inactive version(s) of upgraded port(s)</term>
    547 
    548         <listitem>
    549           <para>makes sense if you are sure that you won't change back to the older version(s)
    550           (which could be necessary in case of newly introduced bugs in the upgraded port version):</para>
    551 
    552           <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
    553           <screen>The following ports are currently installed:
     531    </section>
     532
     533    <section id="using.common-tasks.removeinactive">
     534      <title>Removing inactive version(s) of upgraded port(s)</title>
     535     
     536      <para>makes sense if you are sure that you won't change back to the older version(s)
     537            (which could be necessary in case of newly introduced bugs in the upgraded port
     538            version):</para>
     539
     540      <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
     541      <screen>The following ports are currently installed:
    554542  makedepend @1.0.2_0</screen>
    555543 
    556           <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
    557           <screen>Password:
     544      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
     545      <screen>Password:
    558546--->  Uninstalling makedepend @1.0.2_0</screen>
    559547
    560           <para>Of course one could also select only a specific inactive port,
    561           but that requires to specify the exact version:</para>
    562           <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
    563           <screen>Password:
     548      <para>Of course one could also select only a specific inactive port,
     549            but that requires to specify the exact version:</para>
     550      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
     551      <screen>Password:
    564552--->  Uninstalling makedepend @1.0.2_0</screen>
    565 
    566         </listitem>
    567       </varlistentry>
    568 
    569 
    570       <varlistentry>
    571         <term>Finding ports depending on a certain port</term>
    572 
    573         <listitem>
    574           <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
    575 
    576           <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
    577 
    578           <screen>mkfontscale
     553    </section>
     554
     555    <section id="using.common-tasks.finddepending">
     556      <title>Finding ports depending on a certain port</title>
     557
     558      <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
     559
     560      <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
     561
     562      <screen>mkfontscale
    579563xorg-libAppleWM
    580564xorg-libX11
     
    587571xscope
    588572xtrap</screen>
    589         </listitem>
    590       </varlistentry>
    591 
    592       <varlistentry>
    593         <term>Finding leaves (nondependent ports)</term>
    594 
    595         <listitem>
    596           <para>can be sometimes worthwhile, since often additional ports get installed when
    597           a specific port is installed. One can imagine that if one keeps installing and
    598           uninstalling ports for some time the MacPorts tree can be swamped with ports actually
    599           not necessary anymore. Leaves can be found issueing the command:</para>
    600 
    601           <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    602           <screen>aalib                          @1.4rc5_4
     573    </section>
     574
     575    <section id="using.common-tasks.findleaves">
     576      <title>Finding leaves (nondependent ports)</title>
     577      <para>can be sometimes worthwhile, since often additional ports get installed when
     578            a specific port is installed. One can imagine that if one keeps installing and
     579            uninstalling ports for some time the MacPorts tree can be swamped with ports actually
     580            not necessary anymore. Leaves can be found issueing the command:</para>
     581
     582      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     583      <screen>aalib                          @1.4rc5_4
    603584autoconf                       @2.68_0
    604585autoconf263                    @2.63_0
     
    607588coreutils                      @8.5_0</screen>
    608589
    609           <para>The following command delivers a similar result, but works much slower (due to additional parsing):</para>
    610           <programlisting><prompt>%%</prompt> <userinput>port list leaves</userinput></programlisting>
    611           <screen>aalib                          @1.4rc5         graphics/aalib
     590      <para>The following command delivers a similar result, but works much slower (due to additional parsing):</para>
     591      <programlisting><prompt>%%</prompt> <userinput>port list leaves</userinput></programlisting>
     592      <screen>aalib                          @1.4rc5         graphics/aalib
    612593autoconf                       @2.68           devel/autoconf
    613594autoconf263                    @2.63           devel/autoconf263
     
    616597coreutils                      @8.5            sysutils/coreutils</screen>
    617598
    618           <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
    619         </listitem>
    620       </varlistentry>
    621 
    622       <varlistentry>
    623         <term>Keep your MacPorts installation lean by defining leaves as requested ports</term>
    624 
    625         <listitem>
    626          
    627           <para>Well, before we come to the procedure of defining your requested ports,
    628           let's have a look at a typical scenario where you want to understand what is
    629           actually installed and what is on the other hand truly necessary for your system.
    630           Say checking leaves of your MacPorts installation gives this output:</para>
    631 
    632           <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    633           <screen>aalib                          @1.4rc5_4
     599      <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
     600          </section>
     601
     602    <section id="using.common-tasks.keeplean">
     603      <title>Keep your MacPorts installation lean by defining leaves as requested ports</title>
     604      <para>Well, before we come to the procedure of defining your requested ports,
     605            let's have a look at a typical scenario where you want to understand what is
     606            actually installed and what is on the other hand truly necessary for your system.
     607            Say checking leaves of your MacPorts installation gives this output:</para>
     608
     609      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     610      <screen>aalib                          @1.4rc5_4
    634611autoconf                       @2.68_0
    635612autoconf263                    @2.63_0
     
    639616physfs                         @2.0.1_0</screen>
    640617
    641           <para>Now it is up to the user to decide what's needed and what is not.
    642           Let's say one certainly would want ports starting with autoconf up to coreutils,
    643           since they are often used in port installation. Set those as requested ports using:</para>
    644 
    645           <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
    646 
    647           <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
    648           know what to make of it, you need to check out what it actually is and which ports needed
    649           its installation at some time in the past.</para>
    650 
    651           <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
    652           <screen>physfs @2.0.1 (devel)
     618      <para>Now it is up to the user to decide what's needed and what is not.
     619            Let's say one certainly would want ports starting with autoconf up to coreutils,
     620            since they are often used in port installation. Set those as requested ports using:</para>
     621
     622      <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
     623
     624      <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
     625            know what to make of it, you need to check out what it actually is and which ports needed
     626            its installation at some time in the past.</para>
     627
     628      <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
     629      <screen>physfs @2.0.1 (devel)
    653630Variants:             debug, universal
    654631
     
    664641Maintainers:          nomaintainer@macports.org</screen>
    665642
    666           <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
    667           find out which ports actually depend on it, perhaps that might ring a bell:</para>
    668 
    669           <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
    670           <screen>fbg                             
     643      <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
     644            find out which ports actually depend on it, perhaps that might ring a bell:</para>
     645
     646      <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
     647      <screen>fbg                             
    671648libsdl_sound                   
    672649lincity-ng                     
    673650netpanzer</screen>
    674651
    675           <para>No, you didn't install netpanzer either,
    676           but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
    677           unfortunately that port was broken (see issue <ulink url="http://trac.macports.org/ticket/24641">#24641</ulink>) when
    678           you were trying to install it... Before you ran into the issue, of course, fbg's dependencies
    679           were resolved by MacPorts, which is why port physfs is still present on your system.
    680           Uff, great, confusion resolved. :-)</para>
    681 
    682           <para>When you've step-by-step figured out which ports you want to keep on your system and
    683           have set them as requested, you'll have a list of unnecessary ports, which might be
    684           eventually as short as this:</para>
    685 
    686           <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    687           <screen>aalib                          @1.4rc5_4
     652      <para>No, you didn't install netpanzer either,
     653            but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
     654            unfortunately that port was broken
     655            (see issue <ulink url="http://trac.macports.org/ticket/24641">#24641</ulink>) when
     656            you were trying to install it... Before you ran into the issue, of course, fbg's
     657            dependencies were resolved by MacPorts, which is why port physfs is still present on
     658            your system. Uff, great, confusion resolved. :-)</para>
     659
     660      <para>When you've step-by-step figured out which ports you want to keep on your system and
     661            have set them as requested, you'll have a list of unnecessary ports, which might be
     662            eventually as short as this:</para>
     663
     664      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
     665      <screen>aalib                          @1.4rc5_4
    688666physfs                         @2.0.1_0 </screen>
    689667
    690           <para>Get rid of them by issuing the command:</para>
    691 
    692           <programlisting><prompt>%%</prompt> <userinput>port uninstall leaves</userinput></programlisting>
    693           <screen>--->  Deactivating physfs @2.0.1_0
     668      <para>Get rid of them by issuing the command:</para>
     669
     670      <programlisting><prompt>%%</prompt> <userinput>port uninstall leaves</userinput></programlisting>
     671      <screen>--->  Deactivating physfs @2.0.1_0
    694672--->  Cleaning physfs
    695673--->  Uninstalling physfs @2.0.1_0
     
    698676--->  Uninstalling aalib @1.4rc5_4</screen>
    699677
    700           <para>Find all installed ports you previously set as requested using:</para>
    701 
    702           <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
    703 
    704           <para>Checking the list of leaves from time to time will help to keep your system
    705           free of too much "garbage". However, keep in mind that some ports may be dependencies
    706           only during the installation of a port (library dependencies, installation or
    707           configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
    708           otherwise you'll see them being installed again and again.</para>
    709 
    710         </listitem>
    711       </varlistentry>
    712 
    713     </variablelist>
    714 
     678      <para>Find all installed ports you previously set as requested using:</para>
     679
     680      <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
     681
     682      <para>Checking the list of leaves from time to time will help to keep your system
     683            free of too much "garbage". However, keep in mind that some ports may be dependencies
     684            only during the installation of a port (library dependencies, installation or
     685            configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
     686            otherwise you'll see them being installed again and again.</para>
     687      </section>
    715688  </section>
    716689
Note: See TracChangeset for help on using the changeset viewer.