Sat Jun 20 04:18:41 2020 UTC ()
doc/guide: add usage statistics for the {pre,do,post}-* targets

Just to give a broad orientation about which of these targets are usual
and which are not.


(rillig)
diff -r1.83 -r1.84 pkgsrc/doc/guide/files/build.xml
cvs diff -r1.83 -r1.84 pkgsrc/doc/guide/files/build.xml (expand / switch to unified diff)

--- pkgsrc/doc/guide/files/build.xml 2020/06/05 17:05:22 1.83
+++ pkgsrc/doc/guide/files/build.xml 2020/06/20 04:18:41 1.84
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1<!-- $NetBSD: build.xml,v 1.83 2020/06/05 17:05:22 rillig Exp $ --> 1<!-- $NetBSD: build.xml,v 1.84 2020/06/20 04:18:41 rillig Exp $ -->
2 2
3<chapter id="build"> 3<chapter id="build">
4 <title>The build process</title> 4 <title>The build process</title>
5 5
6 <sect1 id="build.intro"> 6 <sect1 id="build.intro">
7 <title>Introduction</title> 7 <title>Introduction</title>
8 8
9 <para>This chapter gives a detailed description on how a package is 9 <para>This chapter gives a detailed description on how a package is
10 built. Building a package is separated into different 10 built. Building a package is separated into different
11 <emphasis>phases</emphasis> (for example <varname>fetch</varname>, 11 <emphasis>phases</emphasis> (for example <varname>fetch</varname>,
12 <varname>build</varname>, <varname>install</varname>), all of which are 12 <varname>build</varname>, <varname>install</varname>), all of which are
13 described in the following sections. Each phase is split into 13 described in the following sections. Each phase is split into
14 so-called <emphasis>stages</emphasis>, which take the name of the 14 so-called <emphasis>stages</emphasis>, which take the name of the
@@ -707,49 +707,58 @@ ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site @@ -707,49 +707,58 @@ ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site
707 directory by running <command>make clean</command>. If you want 707 directory by running <command>make clean</command>. If you want
708 to clean the work directories of all dependencies too, use 708 to clean the work directories of all dependencies too, use
709 <command>make clean-depends</command>.</para> 709 <command>make clean-depends</command>.</para>
710 </sect1> 710 </sect1>
711 711
712 <sect1 id="build.helpful-targets"> 712 <sect1 id="build.helpful-targets">
713 <title>Other helpful targets</title> 713 <title>Other helpful targets</title>
714 714
715 <variablelist> 715 <variablelist>
716 <varlistentry> 716 <varlistentry>
717 <term>pre/post-*</term> 717 <term>pre/post-*</term>
718 718
719 <listitem> 719 <listitem>
720 <para>For any of the main targets described in the 720 <para>For any of the main targets described in the previous
721 previous section, two auxiliary targets exist with 721 section (configure, build, install, etc.), two auxiliary
 722 targets exist with
722 <quote>pre-</quote> and <quote>post-</quote> used as a 723 <quote>pre-</quote> and <quote>post-</quote> used as a
723 prefix for the main target's name. These targets are 724 prefix for the main target's name. These targets are
724 invoked before and after the main target is called, 725 invoked before and after the main target is called,
725 allowing extra configuration or installation steps be 726 allowing extra configuration or installation steps be
726 performed from a package's Makefile, for example, which 727 performed from a package's Makefile, for example, which
727 a program's configure script or install target 728 a program's configure script or install target
728 omitted.</para> 729 omitted.</para>
 730
 731 <para>About 5% of the pkgsrc packages define their custom
 732 post-extract target, another 5% define pre-configure, and 10%
 733 define post-install. The other pre/post-* targets are defined
 734 even less often.</para>
729 </listitem> 735 </listitem>
730 </varlistentry> 736 </varlistentry>
731 737
732 <varlistentry> 738 <varlistentry>
733 <term>do-*</term> 739 <term>do-*</term>
734 740
735 <listitem> 741 <listitem>
736 <para>Should one of the main targets do the wrong thing, 742 <para>Should one of the main targets do the wrong thing,
737 and should there be no variable to fix this, you can 743 and should there be no variable to fix this, you can
738 redefine it with the do-* target. (Note that redefining 744 redefine it with the do-* target. (Note that redefining
739 the target itself instead of the do-* target is a bad 745 the target itself instead of the do-* target is a bad
740 idea, as the pre-* and post-* targets won't be called 746 idea, as the pre-* and post-* targets won't be called
741 anymore, etc.) You will not usually need to do 747 anymore, etc.)</para>
742 this.</para> 748
 749 <para>About 15% of the pkgsrc packages override the default
 750 do-install, the other do-* targets are overridden even less
 751 often.</para>
743 </listitem> 752 </listitem>
744 </varlistentry> 753 </varlistentry>
745 754
746 <varlistentry> 755 <varlistentry>
747 <term>reinstall</term> 756 <term>reinstall</term>
748 757
749 <listitem> 758 <listitem>
750 <para>If you did a <command>make install</command> and 759 <para>If you did a <command>make install</command> and
751 you noticed some file was not installed properly, you 760 you noticed some file was not installed properly, you
752 can repeat the installation with this target, which will 761 can repeat the installation with this target, which will
753 ignore the <quote>already installed</quote> flag.</para> 762 ignore the <quote>already installed</quote> flag.</para>
754 763
755 <para>This is the default value of 764 <para>This is the default value of