summaryrefslogtreecommitdiff log msg author committer range
blob: 6649d3521649ee92e82f8d4660887bb5b891727c (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  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{Merging and Unmerging} \note{In this chapter, \i{file} and \i{regular file} have their Unix meanings.} \section{Overview} The merge process merges the contents of the \t{D} directory onto the filesystem under \t{ROOT}\@. This is not a straight copy; there are various subtleties which must be addressed. The unmerge process removes an installed package's files. It is not covered in detail in this specification. \section{Directories} Directories are merged recursively onto the filesystem. The method used to perform the merge is not specified, so long as the end result is correct. In particular, merging a directory may alter or remove the source directory under \t{D}. Ebuilds must not attempt to merge a directory on top of any existing file that is not either a directory or a symlink to a directory. \subsection{Permissions} The owner, group and mode (including set*id and sticky bits) of the directory must be preserved, except as follows: \begin{compactitem} \item Any directory owned by the user used to perform the build must become owned by the root user. \item Any directory whose group is the primary group of the user used to perform the build must have its group be that of the root user. \end{compactitem} On SELinux systems, the SELinux context must also be preserved. Other directory attributes, including modification time, may be discarded. \subsection{Empty directories} Behaviour upon encountering an empty directory is undefined. Ebuilds must not attempt to install an empty directory. \section{Regular Files} Regular files are merged onto the filesystem (but see the notes on configuration file protection, below). The method used to perform the merge is not specified, so long as the end result is correct. In particular, merging a regular file may alter or remove the source file under \t{D}. Ebuilds must not attempt to merge a regular file on top of any existing file that is not either a regular file or a symlink to a regular file. \subsection{Permissions} The owner, group and mode (including set*id and sticky bits) of the file must be preserved, except as follows: \begin{compactitem} \item Any file owned by the user used to perform the build must become owned by the root user. \item Any file whose group is the primary group of the user used to perform the build must have its group be that of the root user. \item The package manager may reduce read and write permissions on executable files that have a set*id bit set. \end{compactitem} On SELinux systems, the SELinux context must also be preserved. Other file attributes may be discarded. \subsection{File modification times} \featurelabel{mtime-preserve} In EAPIs listed in table~\ref{tab:mtime-preserve}, the package manager must preserve modification times of regular files. This includes files being compressed before merging. Exceptions to this are files newly created by the package manager and binary object files being stripped of symbols. When preserving, the seconds part of every regular file's mtime must be preserved exactly. The sub-second part must either be set to zero, or set to the greatest value supported by the operating system and filesystem that is not greater than the sub-second part of the original time. For any given destination filesystem, the package manager must ensure that for any two preserved files $a$, $b$ in that filesystem the relation $\mbox{mtime}(a) \leq \mbox{mtime}(b)$ still holds, if it held under the original image directory. In other EAPIs, the behaviour with respect to file modification times is undefined. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{Preservation of file modification times (mtimes)} \label{tab:mtime-preserve} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{mtimes preserved?}} \\ \midrule 0, 1, 2 & Undefined \\ 3, 4, 5, 6, 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} \subsection{Configuration file protection} \label{sec:config-protect} The package manager must provide a means to prevent user configuration files from being overwritten by any package updates. The profile variables \t{CONFIG_PROTECT} and \t{CONFIG_PROTECT_MASK} (section~\ref{sec:profile-variables}) control the paths for which this must be enforced. In order to ensure interoperability with configuration update tools, the following scheme must be used by all package managers when merging any regular file: \begin{compactenum} \item If the directory containing the file to be merged is not listed in \t{CONFIG_PROTECT}, and is not a subdirectory of any such directory, and if the file is not listed in \t{CONFIG_PROTECT}, the file is merged normally. \item If the directory containing the file to be merged is listed in \t{CONFIG_PROTECT_MASK}, or is a subdirectory of such a directory, or if the file is listed in \t{CONFIG_PROTECT_MASK}, the file is merged normally. \item If no existing file with the intended filename exists, or the existing file has identical content to the one being merged, the file is installed normally. \item Otherwise, prepend the filename with \t{._cfg0000_}. If no file with the new name exists, then the file is merged with this name. \item Otherwise, increment the number portion (to form \t{._cfg0001_}) and repeat step 4. Continue this process until a usable filename is found. \item If 9999 is reached in this way, behaviour is undefined. \end{compactenum} \section{Symlinks} Symlinks are merged as symlinks onto the filesystem. The link destination for a merged link shall be the same as the link destination for the link under \t{D}, except as noted below. The method used to perform the merge is not specified, so long as the end result is correct; in particular, merging a symlink may alter or remove the symlink under \t{D}. Ebuilds must not attempt to merge a symlink on top of a directory. \subsection{Rewriting} Any absolute symlink whose link starts with \t{D} must be rewritten with the leading \t{D} removed. The package manager should issue a notice when doing this. \section{Hard Links} A hard link may be merged either as a single file with links or as multiple independent files. \section{Other Files} Ebuilds must not attempt to install any other type of file (FIFOs, device nodes etc). % 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: