svn commit: r50232 - head/en_US.ISO8859-1/books/porters-handbook/uses
Mathieu Arnold
mat at FreeBSD.org
Fri May 5 10:33:49 UTC 2017
Author: mat
Date: Fri May 5 10:33:47 2017
New Revision: 50232
URL: https://svnweb.freebsd.org/changeset/doc/50232
Log:
Rewrite the USES=shebangfix section.
Reviewed by: bcr
Sponsored by: Absolight
Differential Revision: https://reviews.freebsd.org/D10584
Modified:
head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri May 5 07:06:24 2017 (r50231)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri May 5 10:33:47 2017 (r50232)
@@ -2595,25 +2595,48 @@ USE_PYQT= core doc_build designer_run</p
<para>A lot of software uses incorrect locations for script
interpreters, most notably <filename>/usr/bin/perl</filename>
- and <filename>/bin/bash</filename>. The shebagngfix macro fixes
+ and <filename>/bin/bash</filename>. The shebangfix macro fixes
shebang lines in scripts listed in
<varname>SHEBANG_REGEX</varname>,
<varname>SHEBANG_GLOB</varname>, or
- <varname>SHEBANG_FILES</varname>.
- <varname>SHEBANG_REGEX</varname> contains an extended regular
- expressions, and is used with the <literal>-iregex</literal>
- argument of &man.find.1;. <varname>SHEBANG_GLOB</varname>
- contains a pattern used with the <literal>-name</literal>
- argument of &man.find.1;. The shebangfix macro is run
- from <literal>${WRKSRC}</literal>, so
- <varname>SHEBANG_FILES</varname> can contain paths that
- are relative to <literal>${WRKSRC}</literal>. It can also deal
- with absolute paths if files outside of
- <literal>${WRKSRC}</literal> require patching. For
- example when using <varname>SHEBANG_FILES</varname>:</para>
+ <varname>SHEBANG_FILES</varname>.</para>
- <programlisting>USES= shebangfix
-SHEBANG_FILES= scripts/foobar.pl scripts/*.sh</programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><varname>SHEBANG_REGEX</varname></term>
+
+ <listitem>
+ <para>Contains <emphasis>one</emphasis> extended regular
+ expressions, and is used with the
+ <literal>-iregex</literal> argument of &man.find.1;. See
+ <xref linkend="uses-shebangfix-ex-regex"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SHEBANG_GLOB</varname></term>
+
+ <listitem>
+ <para>Contains a list of patterns used with the
+ <literal>-name</literal> argument of &man.find.1;. See
+ <xref linkend="uses-shebangfix-ex-glob"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SHEBANG_FILES</varname></term>
+
+ <listitem>
+ <para>Contains a list of files or &man.sh.1; globs. The
+ shebangfix macro is run from <literal>${WRKSRC}</literal>,
+ so <varname>SHEBANG_FILES</varname> can contain paths that
+ are relative to <literal>${WRKSRC}</literal>. It can also
+ deal with absolute paths if files outside of
+ <literal>${WRKSRC}</literal> require patching. See <xref
+ linkend="uses-shebangfix-ex-files" />.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>Currently
<application>Bash</application>,
@@ -2653,51 +2676,128 @@ SHEBANG_FILES= scripts/foobar.pl scripts
are typically obsolete paths, or paths used on other
operating systems that are incorrect on &os;. They
will be replaced by the correct path in
- <varname><replaceable>interp</replaceable>_CMD</varname>.
- This list will always be part of
- <varname><replaceable>interp</replaceable>_OLD_CMD</varname>:
- <literal>"/usr/bin/env <replaceable>interp</replaceable>"
- /bin/<replaceable>interp</replaceable>
- /usr/bin/<replaceable>interp</replaceable>
- /usr/local/bin/<replaceable>interp</replaceable></literal>.</para>
+ <varname><replaceable>interp</replaceable>_CMD</varname>.</para>
+
+ <note>
+ <para>These will <emphasis>always</emphasis> be part of
+ <varname><replaceable>interp</replaceable>_OLD_CMD</varname>:
+ <literal>"/usr/bin/env
+ <replaceable>interp</replaceable>"
+ /bin/<replaceable>interp</replaceable>
+ /usr/bin/<replaceable>interp</replaceable>
+ /usr/local/bin/<replaceable>interp</replaceable></literal>.</para>
+ </note>
+
+ <tip>
+ <para><varname><replaceable>interp</replaceable>_OLD_CMD</varname>
+ contain multiple values. Any entry with spaces must be
+ quoted. See <xref
+ linkend="uses-shebangfix-ex-ksh"/>.</para>
+ </tip>
</listitem>
</varlistentry>
</variablelist>
- <para>To add another interpreter, set
- <varname>SHEBANG_LANG</varname>. For example:</para>
+ <important>
+ <para>The fixing of shebangs is done during the
+ <buildtarget>patch</buildtarget> phase. If scripts are
+ created with incorrect shebangs during the
+ <buildtarget>build</buildtarget> phase, the build process (for
+ example, the <filename>configure</filename> script, or the
+ <filename>Makefiles</filename>) must be patched or given the
+ right path (for example, with
+ <varname>CONFIGURE_ENV</varname>,
+ <varname>CONFIGURE_ARGS</varname>,
+ <varname>MAKE_ENV</varname>, or <varname>MAKE_ARGS</varname>)
+ to generate the right shebangs.</para>
- <programlisting>SHEBANG_LANG= lua</programlisting>
+ <para>Correct paths for supported interpreters
+ are available in
+ <literal><replaceable>interp</replaceable>_CMD</literal>.</para>
+ </important>
- <para><literal><replaceable>interp</replaceable>_OLD_CMD</literal>
- will contain multiple values. Any entry with spaces must be
- quoted. For example, if it was not already defined, the
- <application>Ksh</application> entry could be defined as:</para>
+ <example xml:id="uses-shebangfix-ex-lua">
+ <title>Adding Another Interpreter to
+ <literal>USES=shebangfix</literal></title>
+
+ <para>To add another interpreter, set
+ <varname>SHEBANG_LANG</varname>. For example:</para>
+
+ <programlisting>SHEBANG_LANG= lua</programlisting>
+ </example>
+
+ <example xml:id="uses-shebangfix-ex-ksh">
+ <title>Specifying all the Paths When Adding an Interpreter to
+ <literal>USES=shebangfix</literal></title>
+
+ <para>If it was not already defined, and there were no default
+ values for
+ <varname><replaceable>interp</replaceable>_OLD_CMD</varname>
+ and <varname><replaceable>interp</replaceable>_CMD</varname>
+ the <application>Ksh</application> entry could be defined
+ as:</para>
- <programlisting>SHEBANG_LANG= ksh
+ <programlisting>SHEBANG_LANG= ksh
ksh_OLD_CMD= "/usr/bin/env ksh" /bin/ksh /usr/bin/ksh
ksh_CMD= ${LOCALBASE}/bin/ksh</programlisting>
+ </example>
- <para>Some software uses strange locations for an interpreter.
- For example, an application might expect
- <application>Python</application> to be located in
- <filename>/opt/bin/python2.7</filename>. The strange path to be
- replaced can be declared in the port
- <filename>Makefile</filename>:</para>
+ <example xml:id="uses-shebangfix-ex-strange">
+ <title>Adding a Strange Location for an Interpreter</title>
- <programlisting>python_OLD_CMD= /opt/bin/python2.7</programlisting>
+ <para>Some software uses strange locations for an interpreter.
+ For example, an application might expect
+ <application>Python</application> to be located in
+ <filename>/opt/bin/python2.7</filename>. The strange path to
+ be replaced can be declared in the port
+ <filename>Makefile</filename>:</para>
+
+ <programlisting>python_OLD_CMD= /opt/bin/python2.7</programlisting>
+ </example>
+
+ <example xml:id="uses-shebangfix-ex-regex">
+ <title><literal>USES=shebangfix</literal> with
+ <varname>SHEBANG_REGEX</varname></title>
+
+ <para>To fix all the files in
+ <literal>${WRKSRC}/scripts</literal> ending in
+ <filename>.pl</filename>, <filename>.sh</filename>, or
+ <filename>.cgi</filename> do:</para>
+
+ <programlisting>USES= shebangfix
+SHEBANG_REGEX= ./scripts/.*\.(sh|pl|cgi)</programlisting>
+
+ <note>
+ <para><varname>SHEBANG_REGEX</varname> is used by running
+ <command>find -E</command>, which uses modern regular
+ expressions also known as extended regular expressions. See
+ &man.re.format.7; for more information.</para>
+ </note>
+ </example>
+
+ <example xml:id="uses-shebangfix-ex-glob">
+ <title><literal>USES=shebangfix</literal> with
+ <varname>SHEBANG_GLOB</varname></title>
+
+ <para>To fix all the files in <literal>${WRKSRC}</literal>
+ ending in <filename>.pl</filename> or
+ <filename>.sh</filename>, do:</para>
+
+ <programlisting>USES= shebangfix
+SHEBANG_GLOB= *.sh *.pl</programlisting>
+ </example>
+
+ <example xml:id="uses-shebangfix-ex-files">
+ <title><literal>USES=shebangfix</literal> with
+ <varname>SHEBANG_FILES</varname></title>
+
+ <para>To fix the files <filename>script/foobar.pl</filename> and
+ <filename>script/*.sh</filename> in
+ <literal>${WRKSRC}</literal>, do:</para>
- <note>
- <para>The fixing of shebangs is done during the
- <buildtarget>patch</buildtarget> phase. If scripts are
- created with incorrect shebangs during the
- <buildtarget>build</buildtarget> phase, the build process (for
- examples, the <filename>configure</filename> script, or the
- <filename>Makefiles</filename>) must be patched to generate
- the right shebangs. Correct paths for supported interpreters
- are available in
- <literal><replaceable>interp</replaceable>_CMD</literal>.</para>
- </note>
+ <programlisting>USES= shebangfix
+SHEBANG_FILES= scripts/foobar.pl scripts/*.sh</programlisting>
+ </example>
</sect1>
<sect1 xml:id="uses-sqlite">
More information about the svn-doc-all
mailing list