PSARC/2007/047 /usr/gnu Stephen Hahn (sch@sun.com), Rainer Orth (ro@techfak.uni-bielefeld.de), and Bart Smaalders (barts@eng.sun.com) ident "$Hg: d-usr-gnu-fast-track.txt 724d1929c863 2007/02/20 13:38:45 -0800 $ SMI" 1. Summary A new directory hierarchy, to contain otherwise-name-conflicting GNU utilities under their original names, is proposed. A guideline for the provision of 'g'-prefixed variants in /usr/bin is also presented. This case seeks Patch release binding. 2. Discussion In an attempt to provide a more complete offering for software developers on OpenSolaris distributions (as well as more general goals of including useful software), this case proposes the introduction of /usr/gnu as a location for alternate implementations of standard tools produced by the GNU project. This case supplements PSARC/2005/185, "Enabling serendipitous discovery" [1]. The goals of the two cases are aligned; this case proposes refinements to the handling of specific scenarios. For the purposes of determining candidates for the GNU environment, the GNU packages of the FSF/UNESCO Free Software Directory are considered the authoritative list [2]. This case, therefore, does not determine how conflicting variant implementations from other sources could be integrated into the filesystem(5) namespace. It does, however, assume that there is no OSS collection of variant implementations of equal significance--in terms of acceptance, utilization, and dependencies--to the FSF/GNU collection. The utilities permitted for integration by this case are those concerned with compilation, data manipulation, personal productivity, and the like--basic applications. Integration of utilities presenting an alternative administrative model, such as a variant implementation of ifconfig(1M), are not in line with the goals behind this case, and as such are strongly discouraged. 2.1. Expected use Much like the use of the XPG4 [3], XPG6 [4], and SunOS/BSD compatibility environments, the expected use of the /usr/gnu environment is to prefer its binary components to the system defaults, via a setting like PATH=/usr/gnu/bin:...:/usr/bin Traditionally, the commands environments are incomplete: they do not provide entries for each and every command available in /usr/bin. In the past, the environments have also been proper subsets of the system default commands: there are no commands that are not also present in the system's default command environment. In the case that an environment composed of the non-conflicting GNU components plus the historical variants is desired, PATH=/usr/bin:... is sufficient. The manual page path will be managed similarly. (Use of the per-section ordering support man(1) allows in MANPATH was considered, but is not suitable for heterogeneous environments.) Like the existing compatibility environments, only the name-conflicting command variants will be present in /usr/gnu/bin and similar directories; non-conflicting commands will be placed in /usr/bin [1]. Although an environment could be further modified to be a full alternative commands environment, that aspect is left to a future case. 2.2. Reliance on /usr/gnu/bin utilities The individual utilities' stability levels dictate their appropriateness for use by other components. 2.3. Utility parity requirements PSARC, in its opinion for PSARC/2005/683 [5 - 6], made policy a technical requirement that XPG4 and XPG6 extensions be also made available in the /usr/bin variant of the affected utility. This policy is not a requirement for the /usr/gnu environment; project teams may choose to enhance partially or completely the /usr/bin variant as part of providing a /usr/gnu utility. (As an aside, project teams stuck on replacement of, enhancement of, or providing an additional variant for a particular command should recognize that their decision may have architectural aspects--shared components and comparative stabilites, for example--but is primarily an economic one. For instance, if an upstream variant is abandoned or undergoing remarkable change, then it is unlikely to have economic advantages over enhancing a known variant.) 2.4. 'g' Prefixing Historically, introduction of GNU utilities into /usr/bin has been done with a 'g' character prefixed to the utility name. This proposal amends this practice: the 'g'-prefixed variant should be provided if already introduced. In cases where another operating system has provided a 'g'-prefixed variant, the project team introducing an otherwise-name-conflicting GNU component may choose to also provide one; otherwise, additional 'g'-prefixed components in /usr/bin (or any other path) are discouraged. GNU components that do not conflict with existing or anticipated components in the system's default commands environment should not be placed in /usr/gnu, and do not require 'g'-prefixing. Exceptions should reference specific examples--other operating systems, dependent software, etc.--supporting the common use or inclusion of the 'g'-prefixed name. Both 'g'-prefixed and non-conflicting interfaces will provide access via /usr/share/man to their manual pages. (Such access may be implemented via symbolic links, for example.) 2.5. Library components Although the primary focus of this case is the introduction of /usr/gnu for commands components, we can also make recommendations for the provision of library components under /usr/gnu. Similar to the commands, conflicting libraries should be placed in /usr/gnu/lib. In addition, non-conflicting libraries that depend on a conflicting library should also be placed only in /usr/gnu/lib. Otherwise, non-conflicting libraries should be placed in /usr/gnu/lib, with appropriate symbolic links in the appropriate /usr/lib subdirectories. At this point, it is recommended that components that introduce a "libexec" directory [7] leave that directory under the /usr/gnu hierarchy. Once a non-GNU component introduces /usr/libexec, this recommendation can be reviewed. 2.6. Other filesystem locations With the introduction of zones, customizable directories must be kept out of /usr to make sparse zones practical. This case reserves /etc/gnu and /var/gnu and their subdirectories as locations for customizable files required by the tools present in the environment, but does not mandate their introduction until an explicit consumer is proposed. Since the GNU components, while the primary sources, are not the sole sources of Info format documentation, and due to the nature of the Info "dir" file, the Info files shall be installed in /usr/share/info. This directory and /usr/gnu/share/info are expected to be equivalent--separated sets of Info documents (GNU components alone and the complete Info set) are not required by this proposal. Otherwise, and with the exception of the 'g'-prefixed components and the recommendation on library components above, the /usr/gnu hierarchy will be populated in accordance with the GNU coding standards [7]. (The specific exceptions are that the localstatedir and sharedstatedir settings will be "/var/gnu" and "/var/gnu/com", respectively, and the sysconfdir will be "/etc/gnu".) The most common directories are given in the Interface Table in Section 3. (The preceeding paragraph implies that use of /usr/gnu/var and /usr/gnu/etc is forbidden; at a minimum, invocations of an Autoconf configure script must read ./configure --prefix=/usr/gnu --localstatedir=/var/gnu --sharedstatedir=/var/gnu/com --sysconfdir=/etc/gnu or have installation rules that are equivalent, barring case-specific exceptions.) 2.7. Manual page modifications Because the commands involved may change at distinctly different rates than the Single Unix specification, it seems prudent to modify the manual pages of GNU components separately from the manual page of a conflicting base components. (In contrast, OpenSolaris manual pages have unified base and XPG4/XPG6 variants into a single page.) On each manual page associated with a conflicting command, a sentence similar to the following will be added to the "NOTES" section: The FSF/GNU implementation of the 'ls' command can be found at /usr/gnu/bin/ls. (See gnu(5) for additional details on FSF/GNU commands.) The "SEE ALSO" section will minimally point to gnu(5). Furthermore, the filesystem(5) page will carry an additional paragraph in the /usr section, such as /usr/gnu GNU commands environment: executables, documentation, and supporting files. with gnu(5) additionally referenced in the "SEE ALSO" section. 2.8. Packaging and availability In general, project teams are strongly encouraged to match a package boundary to the upstream source boundary. By default, these new packages should be made available in either the User or Developer metacluster, to increase the likelihood of their availability in typical installations. 2.9. Future possibilities One possible future direction is to extract the legacy tools from /usr/{bin,sbin} and provide them in a new, stable path like /usr/sunos/{bin,sbin}. The selection of the top-level /usr components can then be made a configurable aspect of the system, via one or more mechanisms. This change might also involve the provision of complete commands environments, as mentioned in Section 2.1. 3. Interfaces /usr/share/info Directory Committed /usr/gnu Directory hierarchy Committed /bin /sbin /include /lib /libexec /share /share/info /share/man /etc/gnu Directory hierarchy Committed /var/gnu Directory hierarchy Committed /com 4. References [1] B. Smaalders, PSARC/2005/185: Enabling serendipitous discovery, 2005. [2] Free Software Foundation, FSF/UNESCO Free Software Directory, "All GNU Packages", 2006 (http://directory.fsf.org/GNU/). [3] J. Tornatore, PSARC/1994/161: XCU4 Conformance (XPG4 Commands/Utilities component), 1994. [4] J. Farley, PSARC/2003/418 SUSv3 Project Update, 2003. [5] C. Fields, PSARC/2005/683: Add /usr/xpg4/bin/crontab and /usr/xpg6/bin/crontab, 2005. [6] B. Sommerfeld et al, PSARC/2005/683 Opinion, 2005. [7] Free Software Foundation, GNU Coding Standards, 2006 (http://www.gnu.org/prep/standards/standards.html#Directory-Variables).