diff options
Diffstat (limited to 'function-reference/install-functions/text.xml')
| -rw-r--r-- | function-reference/install-functions/text.xml | 153 |
1 files changed, 121 insertions, 32 deletions
diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index 1feb198..0d37980 100644 --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -1,13 +1,12 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/install-functions/"> <chapter> <title>Install Functions Reference</title> <body> <p> -The following functions, which are all provided by <c>ebuild.sh</c> and the standard -library, handle various install-related tasks. <c>${D}</c> is automatically handled -for all of these functions. +The following functions are provided by the package manager to handle various +install-related tasks. <c>${ED}</c> is prepended automatically to the install location. </p> <p> @@ -16,6 +15,10 @@ targets. The <c>new*</c> functions take exactly two arguments (except as noted) the first is the source name, the second the name to use when installing. </p> +<p> +The <c>*into</c> functions create the directory if it does not already exist. +</p> + <table> <tr> <th> @@ -33,9 +36,9 @@ the first is the source name, the second the name to use when installing. Change install location for <c>dobin</c>, <c>newbin</c>, <c>dosbin</c>, <c>newsbin</c>, - <c>doman</c>, <c>newman</c>, - <c>doinfo</c>, <c>newinfo</c>, - <c>dolib</c>, <c>newlib</c> + <c>dolib</c>, + <c>dolib.a</c>, <c>newlib.a</c>, + <c>dolib.so</c>, <c>newlib.so</c> </ti> </tr> <tr> @@ -67,7 +70,7 @@ the first is the source name, the second the name to use when installing. <c>insopts</c> </ti> <ti> - Specify arguments passed to <c>install</c> (eg <c>-s</c>, <c>-m644</c>). + Specify arguments passed to <c>install</c> (eg <c>-s</c>, <c>-m644</c>) </ti> </tr> <tr> @@ -92,6 +95,7 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Specify arguments passed to <c>install</c> for libraries + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -99,7 +103,10 @@ the first is the source name, the second the name to use when installing. <c>dobin</c> </ti> <ti> - Install a binary + Install a binary into subdirectory <c>bin</c> of the location provided + by <c>into</c> (resulting in <c>/usr/bin</c> by default) with mode 0755 + and with ownership set to superuser or its equivalent on the system or + installation at hand </ti> </tr> <tr> @@ -115,7 +122,9 @@ the first is the source name, the second the name to use when installing. <c>dodir</c> </ti> <ti> - Install a directory + Install a directory that will be non-empty when the package is + merged. For directories that will be empty, please use + <c>keepdir</c> instead. </ti> </tr> <tr> @@ -123,7 +132,19 @@ the first is the source name, the second the name to use when installing. <c>dodoc</c> </ti> <ti> - Install a documentation file + Install a documentation file into <c>/usr/share/doc/${PF}</c>. + The <c>-r</c> option allows directories to be installed recursively. + </ti> + </tr> + <tr> + <ti> + <c>einstalldocs</c> + </ti> + <ti> + Installs the files and directories specified by the <c>DOCS</c> + and <c>HTML_DOCS</c> variables into <c>/usr/share/doc/${PF}</c> + recursively using <c>dodoc -r</c>. <b>Note</b>: Approved in EAPI + 6. </ti> </tr> <tr> @@ -139,15 +160,18 @@ the first is the source name, the second the name to use when installing. <c>doexe</c> </ti> <ti> - Install an executable + Install an executable into the location provided by <c>exeinto</c>, + by default with mode 0755 or with the install options set by + <c>exeopts</c> </ti> </tr> <tr> <ti> - <c>dohard</c> + <c>doheader</c> </ti> <ti> - Create a hardlink to the first argument from the second argument + Install a header file into <c>/usr/include</c>. + The <c>-r</c> option allows directories to be installed recursively. </ti> </tr> <tr> @@ -156,6 +180,10 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Installs HTML document files into <c>/usr/share/doc/${PF}/html</c> + The <c>-r</c> option allows directories to be installed recursively. + <b>Note</b>: Deprecated in EAPI 6, switch to <c>einstalldocs</c> + instead. + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -179,7 +207,10 @@ the first is the source name, the second the name to use when installing. <c>doins</c> </ti> <ti> - Install a miscellaneous file + Install a miscellaneous file. + The <c>-r</c> option allows directories to be installed recursively. + Any symlinks encountered are installed as symlinks, when installing + recursively. </ti> </tr> <tr> @@ -188,6 +219,7 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Install a library file + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -211,7 +243,17 @@ the first is the source name, the second the name to use when installing. <c>doman</c> </ti> <ti> - Install a man page + <p> + Install a man page into the appropriate section of <c>/usr/share/man</c>. + e.g., <c>foo.1</c> will be installed in <c>/usr/share/man/man1/foo.1</c>. + </p> + <p> + If the man page is named <c>foo.<lang>.1</c> then it will be + installed in <c>/usr/share/man/<lang>/man1/foo.1</c>, where + <c><lang></c> is a language code. Option <c>-i18n=<lang></c> + can be used to explicitly specify a subdirectory (or to suppress it, if + empty). + </p> </ti> </tr> <tr> @@ -219,7 +261,8 @@ the first is the source name, the second the name to use when installing. <c>domo</c> </ti> <ti> - Install a Gettext <c>.mo</c> file + Install a Gettext <c>.mo</c> file. + (EAPI=7) No longer looks at the value of <c>into</c> </ti> </tr> <tr> @@ -235,7 +278,16 @@ the first is the source name, the second the name to use when installing. <c>dosym</c> </ti> <ti> - Create a symlink from the second parameter to the first parameter + <p> + Create a symlink to the target specified as the first parameter, at the + path specified by the second parameter. With option <c>-r</c> (EAPI 8), + an absolute path specified for the target will be converted to a path + relative to the link location. + </p> + <p> + Note: Without option <c>-r</c>, an absolute link target is interpreted + <e>verbatim</e>, i.e. it must include <c>${EPREFIX}</c> when applicable. + </p> </ti> </tr> <tr> @@ -243,7 +295,7 @@ the first is the source name, the second the name to use when installing. <c>fowners</c> </ti> <ti> - Call <c>chown</c> on the specified files in <c>${D}</c> + Call <c>chown</c> on the specified files in <c>${ED}</c> </ti> </tr> <tr> @@ -251,7 +303,7 @@ the first is the source name, the second the name to use when installing. <c>fperms</c> </ti> <ti> - Call <c>chmod</c> on the specified files in <c>${D}</c> + Call <c>chmod</c> on the specified files in <c>${ED}</c> </ti> </tr> <tr> @@ -259,7 +311,15 @@ the first is the source name, the second the name to use when installing. <c>keepdir</c> </ti> <ti> - Create a directory with an empty <c>.keep</c> file in it. + Install a directory that will be empty when the package is + merged. This is like <c>dodir</c>, but for empty directories + instead. <uri + link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">The + handling of empty directories is undefined by the package + manager specification</uri>, and the <c>keepdir</c> function + exists to ensure that the (otherwise empty) directory is + tracked. This is accomplished by installing a hidden file + prefixed with <c>.keep</c> to the directory in question. </ti> </tr> <tr> @@ -267,7 +327,7 @@ the first is the source name, the second the name to use when installing. <c>newbin</c> </ti> <ti> - Install a binary using the second argument as the name. + Install a binary using the second argument as the name </ti> </tr> <tr> @@ -275,7 +335,7 @@ the first is the source name, the second the name to use when installing. <c>newconfd</c> </ti> <ti> - Install an <c>/etc/conf.d</c> entry using the second argument as the name. + Install an <c>/etc/conf.d</c> entry using the second argument as the name </ti> </tr> <tr> @@ -283,7 +343,7 @@ the first is the source name, the second the name to use when installing. <c>newdoc</c> </ti> <ti> - Install a documentation file using the second argument as the name. + Install a documentation file using the second argument as the name </ti> </tr> <tr> @@ -291,7 +351,7 @@ the first is the source name, the second the name to use when installing. <c>newenvd</c> </ti> <ti> - Install an <c>/etc/env.d</c> file using the second argument as the name. + Install an <c>/etc/env.d</c> file using the second argument as the name </ti> </tr> <tr> @@ -299,7 +359,15 @@ the first is the source name, the second the name to use when installing. <c>newexe</c> </ti> <ti> - Install an executable file using the second argument as the name. + Install an executable file using the second argument as the name + </ti> + </tr> + <tr> + <ti> + <c>newheader</c> + </ti> + <ti> + Install a header file using the second argument as the name </ti> </tr> <tr> @@ -307,7 +375,7 @@ the first is the source name, the second the name to use when installing. <c>newinitd</c> </ti> <ti> - Install an <c>/etc/init.d</c> file using the second argument as the name. + Install an <c>/etc/init.d</c> file using the second argument as the name </ti> </tr> <tr> @@ -315,7 +383,7 @@ the first is the source name, the second the name to use when installing. <c>newins</c> </ti> <ti> - Install a miscellaneous file using the second argument as the name. + Install a miscellaneous file using the second argument as the name </ti> </tr> <tr> @@ -323,7 +391,7 @@ the first is the source name, the second the name to use when installing. <c>newlib.a</c> </ti> <ti> - Install a <c>.a</c> library file using the second argument as the name. + Install a <c>.a</c> library file using the second argument as the name </ti> </tr> <tr> @@ -331,7 +399,7 @@ the first is the source name, the second the name to use when installing. <c>newlib.so</c> </ti> <ti> - Install a <c>.so</c> library file using the second argument as the name. + Install a <c>.so</c> library file using the second argument as the name </ti> </tr> <tr> @@ -339,7 +407,7 @@ the first is the source name, the second the name to use when installing. <c>newman</c> </ti> <ti> - Install a manual page using the second argument as the name. + Install a manual page using the second argument as the name </ti> </tr> <tr> @@ -347,7 +415,28 @@ the first is the source name, the second the name to use when installing. <c>newsbin</c> </ti> <ti> - Install an <c>sbin</c> file using the second argument as the name. + Install an <c>sbin</c> file using the second argument as the name + </ti> + </tr> + <tr> + <ti> + <c>docompress</c> + </ti> + <ti> + Controls compression of files. Normally executed to exclude from + compression, e.g., <c>docompress -x /usr/share/doc/${PF}/examples</c>. + </ti> + </tr> + <tr> + <ti> + <c>dostrip</c> + </ti> + <ti> + Controls stripping of executables. Normally used to exclude from + stripping, e.g. <c>dostrip -x /usr/$(get_libdir)/important.so</c>. + May also be used without the <c>-x</c> option to include binaries to + strip when <c>RESTRICT=strip</c> is set. Provided paths are relative + to <c>${ED}</c>, even if they begin with a slash. </ti> </tr> </table> |