summaryrefslogtreecommitdiff log msg author committer range
blob: 38e1be1245f64fcc3a5c7dbdaf0dfb9906f0f1b1 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246  pre { line-height: 125%; } td.linenos pre { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } span.linenos { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } td.linenos pre.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } .highlight .hll { background-color: #ffffcc } .highlight .c { color: #888888 } /* Comment */ .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ .highlight .k { color: #008800; font-weight: bold } /* Keyword */ .highlight .ch { color: #888888 } /* Comment.Hashbang */ .highlight .cm { color: #888888 } /* Comment.Multiline */ .highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */ .highlight .cpf { color: #888888 } /* Comment.PreprocFile */ .highlight .c1 { color: #888888 } /* Comment.Single */ .highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */ .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ .highlight .gr { color: #aa0000 } /* Generic.Error */ .highlight .gh { color: #333333 } /* Generic.Heading */ .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ .highlight .go { color: #888888 } /* Generic.Output */ .highlight .gp { color: #555555 } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #666666 } /* Generic.Subheading */ .highlight .gt { color: #aa0000 } /* Generic.Traceback */ .highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */ .highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */ .highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */ .highlight .kp { color: #008800 } /* Keyword.Pseudo */ .highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */ .highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */ .highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */ .highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */ .highlight .na { color: #336699 } /* Name.Attribute */ .highlight .nb { color: #003388 } /* Name.Builtin */ .highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */ .highlight .no { color: #003366; font-weight: bold } /* Name.Constant */ .highlight .nd { color: #555555 } /* Name.Decorator */ .highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */ .highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */ .highlight .nl { color: #336699; font-style: italic } /* Name.Label */ .highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */ .highlight .py { color: #336699; font-weight: bold } /* Name.Property */ .highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #336699 } /* Name.Variable */ .highlight .ow { color: #008800 } /* Operator.Word */ .highlight .w { color: #bbbbbb } /* Text.Whitespace */ .highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */ .highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */ .highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */ .highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */ .highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */ .highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */ .highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */ .highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */ .highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */ .highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */ .highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */ .highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */ .highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */ .highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */ .highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */ .highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */ .highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */ .highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */ .highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */\chapter{Profiles} \label{ch:profiles} \section{General Principles} Generally, a profile defines information specific to a certain type' of system---it lies somewhere between repository-level defaults and user configuration in that the information it contains is not necessarily applicable to all machines, but is sufficiently general that it should not be left to the user to configure it. Some parts of the profile can be overridden by user configuration, some only by another profile. The format of a profile is relatively simple. Each profile is a directory containing any number of the files described in this chapter, and possibly inheriting another profile. The files themselves follow a few basic conventions as regards inheritance and format; these are described in the next section. It may also contain any number of subdirectories containing other profiles. \section{Files That Make up a Profile} \subsection{The parent file} A profile may contain a \t{parent} file. Each line must contain a relative path to another profile which will be considered as one of this profile's parents. Any settings from the parent are inherited by this profile, and can be overridden by it. Precise rules for how settings are combined with the parent profile vary between files, and are described below. Parents are handled depth first, left to right, with duplicate parent paths being sourced for every time they are encountered. It is illegal for a profile's parent tree to contain cycles. Package manager behaviour upon encountering a cycle is undefined. This file must not contain comments, blank lines or make use of line continuations. \subsection{The eapi file} \label{sec:profile-eapi} A profile directory may contain an \t{eapi} file. This file, if it exists, must contain a single line with the name of an EAPI\@. This specifies the EAPI to use when handling the directory in question; a package manager must not attempt to use any profile using a directory which requires an EAPI it does not support. If no \t{eapi} file is present, EAPI 0 shall be used. The EAPI is neither inherited via the \t{parent} file nor in subdirectories. \subsection{deprecated} If a profile contains a file named \t{deprecated}, it is treated as such. The first line of this file should contain the path from the \t{profiles} directory of the repository to a valid profile that is the recommended upgrade path from this profile. The remainder of the file can contain any text, which may be displayed to users using this profile by the package manager. This file is not inherited---profiles which inherit from a deprecated profile are \e{not} deprecated. This file must not contain comments or make use of line continuations. \subsection{make.defaults} \t{make.defaults} is used to define defaults for various environment and configuration variables. This file is unusual in that it is not combined at a file level with the parent---instead, each variable is combined or overridden individually as described in section~\ref{sec:profile-variables}. The file itself is a line-based key-value format. Each line contains a single \verb|VAR="value"| entry, where the value must be double quoted. A variable name must start with one of \t{a-zA-Z} and may contain \t{a-zA-Z0-9_} only. Additional syntax, which is a small subset of bash syntax, is allowed as follows: \begin{compactitem} \item Variables to the right of the equals sign in the form \t{\$\{foo\}} or \t{\$foo} are recognised and expanded from variables previously set in this or earlier \t{make.defaults} files. \item One logical line may be continued over multiple physical lines by escaping the newline with a backslash. A quoted string may be continued over multiple physical lines by either a simple newline or a backslash-escaped newline. \item Backslashes, except for line continuations, are not allowed. \end{compactitem} \subsection{Simple line-based files} \label{sec:line-stacking} These files are a simple one-item-per-line list, which is inherited in the following manner: the parent profile's list is taken, and the current profile's list appended. If any line begins with a hyphen, then any lines previous to it whose contents are equal to the remainder of that line are removed from the list. Once again, blank lines and those beginning with a \# are discarded. \featurelabel{profile-file-dirs} In EAPIs listed in table~\ref{tab:profile-file-dirs} as supporting directories for profile files, any of the files \t{package.mask}, \t{package.use}, \t{use.*} and \t{package.use.*} mentioned below can be a directory instead of a regular file. Files contained in that directory, unless their name begins with a dot, will be concatenated in order of their filename in the POSIX locale and the result will be processed as if it were a single file. Any subdirectories will be ignored. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting directories for profile files} \label{tab:profile-file-dirs} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports directories for profile files?}} \\ \midrule 0, 1, 2, 3, 4, 5, 6 & No \\ 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} \subsection{packages} The \t{packages} file is used to define the system set' for this profile. After the above rules for inheritance and comments are applied, its lines must take one of two forms: a package dependency specification prefixed by \t{*} denotes that it forms part of the system set. A package dependency specification on its own may also appear for legacy reasons, but should be ignored when calculating the system set. \subsection{packages.build} The \t{packages.build} file is used by Gentoo's Catalyst tool to generate stage1 tarballs, and has no relevance to the operation of a package manager. It is thus outside the scope of this document, but is mentioned here for completeness. \subsection{package.mask} \t{package.mask} is used to prevent packages from being installed on a given profile. Each line contains one package dependency specification; anything matching this specification will not be installed unless unmasked by the user's configuration. In some EAPIs, \t{package.mask} can be a directory instead of a regular file as per section~\ref{sec:line-stacking}. Note that the \t{-spec} syntax can be used to remove a mask in a parent profile, but not necessarily a global mask (from \t{profiles/package.mask}, section~\ref{sec:profiles-dir}). \note{Portage currently treats \t{profiles/package.mask} as being on the leftmost branch of the inherit tree when it comes to \t{-lines}. This behaviour may not be relied upon.} \subsection{package.provided} \featurelabel{package-provided} \t{package.provided} is used to tell the package manager that a certain package version should be considered to be provided by the system regardless of whether it is actually installed. Because it has severe adverse effects on USE-based and slot-based dependencies, its use is strongly deprecated and package manager support must be regarded as purely optional. Supported in EAPIs as per table~\ref{tab:package-provided}. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting \t{package.provided} in profiles} \label{tab:package-provided} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{package.provided}?}} \\ \midrule 0, 1, 2, 3, 4, 5, 6 & Optionally \\ 7 & No \\ \bottomrule \end{tabular} \end{centertable} \subsection{package.use} The \t{package.use} file may be used by the package manager to override the default USE flags specified by \t{make.defaults} on a per package basis. The format is to have a package dependency specification, and then a space delimited list of USE flags to enable. A USE flag in the form of \t{-flag} indicates that the package should have the USE flag disabled. The package dependency specification is limited to the forms defined by the directory's EAPI\@. In some EAPIs, \t{package.use} can be a directory instead of a regular file as per section~\ref{sec:line-stacking}. \subsection{USE masking and forcing} \label{sec:use-masking} This section covers the eight files \t{use.mask}, \t{use.force}, \t{use.stable.mask}, \t{use.stable.force}, \t{package.use.mask}, \t{package.use.force}, \t{package.use.stable.mask}, and \t{package.use.\allowbreak stable.force}. They are described together because they interact in a non-trivial manner. In some EAPIs, these files can be directories instead of regular files as per section~\ref{sec:line-stacking}. Simply speaking, \t{use.mask} and \t{use.force} are used to say that a given USE flag must never or always, respectively, be enabled when using this profile. \t{package.use.mask} and \t{package.use.force} do the same thing on a per-package, or per-version, basis. \featurelabel{stablemask} In profile directories with an EAPI supporting stable masking, as listed in table~\ref{tab:profile-stablemask}, the same is true for \t{use.stable.mask}, \t{use.stable.force}, \t{package.use.stable.mask} and \t{package.use.\allowbreak stable.force}. These files, however, only act on packages that are merged due to a stable keyword in the sense of subsection~\ref{sec:keywords}. Thus, these files can be used to restrict the feature set deemed stable in a package. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{Profile directory support for masking/forcing use flags in stable versions only} \label{tab:profile-stablemask} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports masking/forcing use flags in stable versions?}} \\ \midrule 0, 1, 2, 3, 4 & No \\ 5, 6, 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} The precise manner in which the eight files interact is less simple, and is best described in terms of the algorithm used to determine whether a flag is masked for a given package version. This is described in algorithm~\ref{alg:use-masking}. \begin{algorithm} \caption{\t{USE} masking logic} \label{alg:use-masking} \begin{algorithmic}[1] \STATE let masked = false \FOR{each profile in the inheritance tree, depth first} \IF{\t{use.mask} contains \i{flag}} \STATE let masked = true \ELSIF{\t{use.mask} contains \i{-flag}} \STATE let masked = false \ENDIF \IF{stable keyword in use} \IF{\t{use.stable.mask} contains \i{flag}} \STATE let masked = true \ELSIF{\t{use.stable.mask} contains \i{-flag}} \STATE let masked = false \ENDIF \ENDIF \FOR{each $line$ in package.use.mask, in order, for which the spec matches $package$} \IF{$line$ contains \i{flag}} \STATE let masked = true \ELSIF{$line$ contains \i{-flag}} \STATE let masked = false \ENDIF \ENDFOR \IF{stable keyword in use} \FOR{each $line$ in package.use.stable.mask, in order, for which the spec matches $package$} \IF{$line$ contains \i{flag}} \STATE let masked = true \ELSIF{$line$ contains \i{-flag}} \STATE let masked = false \ENDIF \ENDFOR \ENDIF \ENDFOR \end{algorithmic} \end{algorithm} Stable restrictions (stable keyword in use'' in algorithm~\ref{alg:use-masking}) are applied exactly if replacing in \t{KEYWORDS} all stable keywords by the corresponding tilde prefixed keywords (see subsection~\ref{sec:keywords}) would result in the package installation being prevented due to the \t{KEYWORDS} setting. The logic for \t{use.force}, \t{use.stable.force}, \t{package.use.force}, and \t{package.use.\allowbreak stable.force} is identical. If a flag is both masked and forced, the mask is considered to take precedence. \t{USE_EXPAND} values may be forced or masked by using \t{expand_name_value}. A package manager may treat \t{ARCH} values that are not the current architecture as being masked. \input{profile-variables.tex} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : %%% Local Variables: %%% mode: latex %%% TeX-master: "pms" %%% LaTeX-indent-level: 4 %%% LaTeX-item-indent: 0 %%% TeX-brace-indent-level: 4 %%% fill-column: 100 %%% End: