Date: Fri, 5 May 2017 10:33:48 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50232 - head/en_US.ISO8859-1/books/porters-handbook/uses Message-ID: <201705051033.v45AXmRp097715@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201705051033.v45AXmRp097715>