From: Steve Youngs Date: Sat, 6 Jun 2015 04:04:44 +0000 (+1000) Subject: XDG Compliant user package tree -- doc updates. X-Git-Tag: v22.1.16~45^2 X-Git-Url: https://cgit.sxemacs.org/?a=commitdiff_plain;h=1ae91c6195b2f2f8e645dd0774b4efad0fbb8b79;p=sxemacs XDG Compliant user package tree -- doc updates. This updates the documentation to reflect the new location for user (early) packages. * PROBLEMS: Add section about early-packages locations. * README.packages: Update the text relating to user packages. * etc/sxemacs.1 (FILES): Ditto. * info/lispref/packaging.texi (The User View): Update. * info/new-users-guide/custom2.texi (Init File): Typo fix. * info/sxemacs-faq.texi (Q5.3.3): Ditto. * info/sxemacs/cmdargs.texi (Command Switches): Add -user-pkgs-directory. * info/sxemacs/startup.texi (Startup Paths): Update for current reality. Signed-off-by: Steve Youngs --- diff --git a/PROBLEMS b/PROBLEMS index bcebee8..860c56d 100644 --- a/PROBLEMS +++ b/PROBLEMS @@ -32,11 +32,22 @@ file or Gnu/Emacs .emacs file. ** Packages Hierarchy +*** System-wide Packages (late-packages) + The default location that SXEmacs searches for packages is `$prefix/share/sxemacs/'. The same as for the user-init-file, a symlink is all you need to get up and running. - $ ln -s /usr/local/lib/xemacs /usr/local/share/sxemacs RET + $ ln -svfn /usr/local/lib/xemacs /usr/local/share/sxemacs + +*** User Packages in ${HOME} (early-packages) + +For packages that you keep in your ${HOME}, the preferred location is: +${XDG_DATA_HOME}/sxemacs. This is normally ${HOME}/.local/share/sxemacs, +and SXEmacs will use that if ${XDG_DATA_HOME} is not set. + +These packages may also be located in ~/.sxemacs if that is where you +have your user-init-directory set to. * Build Quirks diff --git a/README.packages b/README.packages index a214669..c724fd8 100644 --- a/README.packages +++ b/README.packages @@ -121,7 +121,7 @@ requirements for this to work... automatically detects it if you have it. And this quick test will return `t' if you do... - M-: (fboundp #'ffi-defun) RET + M-: (featurep 'ffi) RET 2. libcurl.so installed. Note that you do not need this library to build SXEmacs. @@ -314,10 +314,16 @@ this for you. * User Package directories -------------------------- -In addition to the system wide packages, each user can have his own -packages installed under "~/.sxemacs/". If you want to install packages -there using the interactive tools, you need to set -'package-get-install-to-user-init-directory' to 't' +In addition to the system wide packages, each user can have their own +packages installed under ${HOME}. The default location is: +${XDG_DATA_HOME}/sxemacs, which is normally ~/.local/share/sxemacs, +and is what SXEmacs will use if ${XDG_DATA_HOME} is not set. + +Alternatively, these packages can be installed under ~/.sxemacs if +that is where you have set your `user-init-diretory' to. + +If you want to install packages into your ${HOME} using the interactive +tools, you need to set 'package-get-install-to-user-directory' to 't' * Site lisp/Site start ---------------------- diff --git a/etc/sxemacs.1 b/etc/sxemacs.1 index a96625b..50da762 100644 --- a/etc/sxemacs.1 +++ b/etc/sxemacs.1 @@ -1,4 +1,4 @@ -.TH SXEMACS 1 "2007-12-29" +.TH SXEMACS 1 "2015-06-05" .UC 4 .SH NAME sxemacs \- Emacs Redefined @@ -626,12 +626,12 @@ Lisp code is read at startup from the user's init file, which can be one of: \fB${XDG_CONFIG_HOME}/sxemacs/init.el\fP - +.br \fB${HOME}/.config/sxemacs/init.el\fP - +.br \fB${HOME}/.sxemacs/init.el\fP -/usr/local/share/info - files for the Info documentation browser +\fB${PREFIX}/share/info\fP - files for the Info documentation browser (a subsystem of .IR SXEmacs ) to refer to. The complete text of the @@ -640,16 +640,16 @@ and the .I SXEmacs Lisp Programmer's Manual is included in a convenient tree structured form. -$PREFIX/share/sxemacs-$VERSION/lisp/* - Lisp source files and compiled files +\fB${PREFIX}/share/sxemacs-$VERSION/lisp/*\fP - Lisp source files and compiled files that define most editing commands. -$PREFIX/share/sxemacs-$VERSION/etc - some files of information, pixmap +\fB${PREFIX}/share/sxemacs-$VERSION/etc\fP - some files of information, pixmap files, other data files used by certain packages, etc. -$PREFIX/lib/sxemacs-$VERSION/$CONFIGURATION - various programs that are used +\fB${PREFIX}/lib/sxemacs-$VERSION/$CONFIGURATION\fP - various programs that are used with SXEmacs. -$PREFIX/lib/sxemacs-$VERSION/$CONFIGURATION/DOC - +\fB${PREFIX}/lib/sxemacs-$VERSION/$CONFIGURATION/DOC\fP - contains the documentation strings for the Lisp primitives and preloaded Lisp functions of \fISXEmacs\fP. They are stored here to reduce the size of \fISXEmacs\fP proper. @@ -657,15 +657,21 @@ They are stored here to reduce the size of \fISXEmacs\fP proper. \fISXEmacs\fP can use the \fIXEmacs\fP package infrastructure and it searches for packages in these places by default... -$HOME/.sxemacs/site-packages -$HOME/.sxemacs/xemacs-packages -$HOME/.sxemacs/mule-packages -$HOME/.sxemacs/sxemacs-packages +\fB${XDG_DATA_HOME}/sxemacs/site-packages\fP +.br +\fB${XDG_DATA_HOME}/sxemacs/xemacs-packages\fP +.br +\fB${XDG_DATA_HOME}/sxemacs/mule-packages\fP +.br +\fB${XDG_DATA_HOME}/sxemacs/sxemacs-packages\fP -$PREFIX/share/sxemacs/site-packages -$PREFIX/share/sxemacs/xemacs-packages -$PREFIX/share/sxemacs/mule-packages -$PREFIX/share/sxemacs/sxemacs-packages +\fB${PREFIX}/share/sxemacs/site-packages\fP +.br +\fB${PREFIX}/share/sxemacs/xemacs-packages\fP +.br +\fB${PREFIX}/share/sxemacs/mule-packages\fP +.br +\fB${PREFIX}/share/sxemacs/sxemacs-packages\fP .PP diff --git a/info/lispref/packaging.texi b/info/lispref/packaging.texi index 2cf3cef..42399d7 100644 --- a/info/lispref/packaging.texi +++ b/info/lispref/packaging.texi @@ -135,33 +135,35 @@ sources, separated by package. (It does not contain @file{man(1)} pages, as Emacs provides very few of them.) There are several standard package hierarchies, and administrators can -configure others at build time, while users can configure others at run -time. The standard system hierarchies are all subdirectories of an -@c #### This is possibly incorrect usage of "installation root." -XEmacs installation root, typically @file{/usr/local/lib/xemacs/}. -These are the @file{xemacs-packages}, @file{mule-packages}, -@file{infodock-packages}, and @file{site-packages} hierarchies. Each -has the structure described above, but the purposes differ. The +configure others at build time, while users can configure others at +run time. The standard system hierarchies are all subdirectories of +@file{$@{PREFIX@}/share/sxemacs/}. These are the @file{site-packages}, +@file{xemacs-packages}, @file{mule-packages}, +@file{infodock-packages}, and @file{sxemacs-packages} hierarchies. +Each has the structure described above, but the purposes differ. The @file{xemacs-packages} is the normal place for installing ``official'' packages and many third-party libraries. Unfortunately, it is not yet quite possible to read libraries containing international characters -with a non-Mule XEmacs, so such libraries are sequestered in the -@file{mule-packages} hierarchy. Some packages are compatible only with -the Infodock development environment, and they will be installed in the -@file{infodock-packages} hierarchy. The @file{site-packages} hierarchy -is for packages not distributed by XEmacs.org, typically locally -developed. - -Packages are in principle supposed to be XEmacs version-independent, but -if such dependencies are unavoidable, additional standard package -hierarchies may be installed under version directories, @emph{e.g.} -@file{/usr/local/lib/xemacs-21.4.6/}. +with a non-Mule SXEmacs, so such libraries are sequestered in the +@file{mule-packages} hierarchy. Some packages are compatible only +with the Infodock development environment, and they will be installed +in the @file{infodock-packages} hierarchy. The @file{site-packages} +hierarchy is for packages not distributed by XEmacs.org, typically +locally developed. + +@c Really don't think this is right --SY +@c Packages are in principle supposed to be XEmacs version-independent, but +@c if such dependencies are unavoidable, additional standard package +@c hierarchies may be installed under version directories, @emph{e.g.} +@c @file{/usr/local/lib/xemacs-21.4.6/}. Users who do not have sufficient privilege to install packages in the -system hierarchies may install package hierarchies under @file{~/.xemacs}. -At present only the @file{xemacs-packages}, @file{mule-packages}, and -@file{site-packages} hierarchies are supported, but it might make sense to -extend this to support @file{infodock-packages} hierarchies in the future. +system hierarchies may install package hierarchies under +@file{@var{$XDG_DATA_HOME}/sxemacs}. At present only the +@file{site-packages}, @file{xemacs-packages}, @file{mule-packages}, +and @file{sxemacs-packages} hierarchies are supported, but it might +make sense to extend this to support @file{infodock-packages} +hierarchies in the future. The package hierarchies are not searched directly for libraries to be loaded; this would be very costly. Instead, the hierarchies are ordered @@ -172,34 +174,58 @@ run-time. This approach is somewhat costly at initialization, but results in a very ``clean'' @code{load-path}. The order of search can be changed at build time by specifying the -@samp{--package-path} option to @file{configure}, or at run-time by +@samp{--with-package-path} option to @file{configure}, or at run-time by specifying the @code{EMACSPACKAGEPATH} environment variable. -@xref{Packages,,,xemacs}. +@xref{Packages,,,sxemacs} +Also, the location for @code{early-packages} may be set via the +@code{-user-pkgs-directory} command line argument (@pxref{Command Swithches}). @c #### The following description is quite possibly inaccurate. @c Please, Michael, write some specs up! -The default order of search is hierarchically determined. First, the -roots are ordered. The @dfn{early} roots are the user-specific roots, -typically @file{~/.xemacs}. The @dfn{late} roots are the system roots, -typically @file{/usr/local/lib/xemacs-21.4.6} and -@file{/usr/local/lib/xemacs}, in that order. All hierarchies for a -given root are searched for package Lisp directories, which are appended -to @code{load-path} in the order found. Then the search proceeds to the -next root, whose results will be appended to the @code{load-path} -generated by previous roots. - -Second, the hierarchies below each root are searched in the order -@file{site-packages}, @file{infodock-packages}, @file{mule-packages}, -then @file{xemacs-packages}. +The default order of search is hierarchically determined. There are 3 +``categories'' of lisp hierarchies in SXEmacs, well, actually there are +4, but we'll get to that in a moment. In order, they are: +@code{early-packages}, @code{late-packages}, and @dfn{core}. + +The @code{early-packages} are the user's local packages, stored +under their @var{$HOME}. Typically, these packages will be in +@file{@var{$XDG_DATA_HOME}/sxemacs}. The @code{late-packages} are the +``system-wide'' packages, typically installed in +@file{@var{$PREFIX}/share/sxemacs}, and @dfn{core} is the lisp that is +shipped with SXEmacs and installed to +@file{@var{$PREFIX}/share/sxemacs-@var{$version}}. + +The @code{early-packages} and @code{late-packages} are further split +into @dfn{package types}. These types are (in search order): +@file{site-packages}, @file{sxemacs-packages}, +@file{infodock-packages}, @file{mule-packages}, and +@file{xemacs-packages}. + +The @dfn{core} lisp is also sub-divided into @file{mule}, @file{ffi}, +and ``normal'', and searched in that order. + +Oh, that 4th category I spoke of earlier, those are the +@file{last-packages}. By default, SXEmacs does not have a +pre-configured @dfn{last} package hierarchy. Last hierarchies are +primarily for using package hierarchies of outdated versions of XEmacs +as a fallback option. For example, it is possible to run SXEmacs with +the XEmacs 20.4 package hierarchy as a last hierarchy. In each hierarchy there should be a @file{lisp} subdirectory, containing directories named for the packages. Each package's Lisp libraries thus are contained in a directory of the form -@var{root}/@var{hierarchy}/lisp/@var{package}/. +@var{category}/@var{type}/lisp/@var{package}/. The 3 directories that +make up the @dfn{core lisp} are, in search order@dots{} + +@smallexample +@var{$PREFIX}/share/sxemacs-@var{version}/lisp/mule +@var{$PREFIX}/share/sxemacs-@var{version}/lisp/ffi +@var{$PREFIX}/share/sxemacs-@var{version}/lisp +@end smallexample With such a complex search algorithm, the possibility of libraries being shadowed by another library with the same name is quite real. There are -two considerations here. First, every XEmacs package contains certain +two considerations here. First, every SXEmacs package contains certain libraries with constant names. These are @table @file diff --git a/info/new-users-guide/custom2.texi b/info/new-users-guide/custom2.texi index e4bca1d..feaa18d 100644 --- a/info/new-users-guide/custom2.texi +++ b/info/new-users-guide/custom2.texi @@ -419,12 +419,12 @@ If you want an extensive menu-bar use the following expression in your @noindent If you want to write your own menus, you can look at some of the examples in -@file{/usr/local/lib/sxemacs/xemacs-packages/lisp/edit-utils/big-menubar.el} file. +@file{/usr/local/share/sxemacs/xemacs-packages/lisp/edit-utils/big-menubar.el} file. @end itemize For more information on initializing your @file{init.el} file, @xref{Init File,,,sxemacs,SXEmacs User's Manual}. You should also look at -@file{/usr/local/lib/sxemacs-VERSION/etc/sample.init.el}, which is a sample +@file{/usr/local/share/sxemacs-VERSION/etc/sample.init.el}, which is a sample @file{init.el} file. It contains some of the commonly desired customizations in Emacs. diff --git a/info/sxemacs-faq.texi b/info/sxemacs-faq.texi index cefc94f..ffd872f 100644 --- a/info/sxemacs-faq.texi +++ b/info/sxemacs-faq.texi @@ -5815,7 +5815,7 @@ document? The package @code{ps-print}, which is now included with SXEmacs, provides the ability to do this. The source code contains complete instructions on its use, in -@file{$prefix/lib/sxemacs/xemacs-packages/lisp/ps-print/ps-print.el}, +@file{$prefix/share/sxemacs/xemacs-packages/lisp/ps-print/ps-print.el}, being the default location of an installed ps-print package. diff --git a/info/sxemacs/cmdargs.texi b/info/sxemacs/cmdargs.texi index 6c21829..b533d4c 100644 --- a/info/sxemacs/cmdargs.texi +++ b/info/sxemacs/cmdargs.texi @@ -212,6 +212,12 @@ Load @var{file} as your SXEmacs init file instead of the default @itemx --user-init-directory @var{directory} Use @var{directory} as the location of your initialization files. +@item -user-pkgs-directory @var{directory} +@itemx --user-pkgs-directory @var{directory} +Use @var{directory} as the location of your local, +@code{early-packages}, hierarchy instead of the +default. @file{@var{$XDG_DATA_HOME}/sxemacs}. + @item -user @var{user} @itemx --user @var{user} @itemx -u @var{user} diff --git a/info/sxemacs/startup.texi b/info/sxemacs/startup.texi index 6a1fc59..6c5a184 100644 --- a/info/sxemacs/startup.texi +++ b/info/sxemacs/startup.texi @@ -64,35 +64,38 @@ up in the various SXEmacs paths. Early package hierarchies are at the very front, late ones somewhere in the middle, and last hierarchies are (you guessed it) last. -By default, SXEmacs expects an early package hierarchy in the -subdirectory @file{.sxemacs/xemacs-packages} of the user's home -directory. - -Moreover, SXEmacs expects late hierarchies in the subdirectories -@file{site-packages}, @file{mule-packages}, @file{xemacs-packages}, and -@file{sxemacs-packages} (in that order) of the @file{/lib/sxemacs} -subdirectory of one of the installation hierarchies. (If you run -in-place, these are direct subdirectories of the build directory.) -Furthermore, SXEmacs will also search these subdirectories in the -@file{/lib/sxemacs-} subdirectory and prefer directories -found there. - -By default, SXEmacs does not have a pre-configured last package +By default, SXEmacs looks for @dfn{early} package hierarchies in +@file{@var{$XDG_DATA_HOME}/sxemacs}, and @dfn{late} package hierarchies in +@file{@var{$PREFIX}/share/sxemacs}. + +Under the @dfn{early} and @dfn{late} hierarchies are the +subdirectories: @file{site-packages}, @file{sxemacs-packages}, +@file{mule-packages}, and @file{xemacs-packages}, which are searched +in that order. (If you run in-place, these are direct subdirectories +of the build directory.) @c really? +@c ### I don't think this is right, is it? --SY +@c Furthermore, SXEmacs will also search these +@c subdirectories in the @file{/lib/sxemacs-} subdirectory +@c and prefer directories found there. + +By default, SXEmacs does not have a pre-configured @dfn{last} package hierarchy. Last hierarchies are primarily for using package hierarchies of outdated versions of XEmacs as a fallback option. For example, it is -possible to run SXEmacs with the 20.4 package hierarchy as a last +possible to run SXEmacs with the XEmacs 20.4 package hierarchy as a last hierarchy. It is possible to specify at configure-time the location of the various -package hierarchies with the @code{--package-path} option to configure. +package hierarchies with the @code{--with-package-path} option to configure. @cindex package path -The early, late, and last components of the package path are separated -by double instead of single colons. If all three components are -present, they locate the early, late, and last package hierarchies -respectively. If two components are present, they locate the early and -late hierarchies. If only one component is present, it locates the -late hierarchy. At run time, the package path may also be specified via -the @code{EMACSPACKAGEPATH} environment variable. +The @dfn{early}, @dfn{late}, and @dfn{last} components of the package path +are separated by double colons instead of single colons. If all three +components are present, they locate the early, late, and last package +hierarchies respectively. If two components are present, they locate the +early and late hierarchies. If only one component is present, it locates +the late hierarchy. At run time, the package path may also be specified +via the @code{EMACSPACKAGEPATH} environment variable. Or, alternatively, +the @dfn{early} hierarchy can be set via the @code{-user-pkgs-directory} +command line argument (@pxref{Command Switches}). An SXEmacs package is laid out just like a normal installed SXEmacs lisp directory. It may have @file{lisp}, @file{etc}, @file{info}, and @@ -113,21 +116,23 @@ when looking for them. @item version-specific @cindex version-specific directories directories are specific to the version of SXEmacs they belong to and -typically reside under @file{/lib/sxemacs-}. +typically reside under @file{/share/sxemacs-}. This is +where you'll find the lisp that is shipped with SXEmacs, we call it +the @dfn{core lisp}. @item site-specific @cindex site-specific directories directories are independent of the version of SXEmacs they belong to and -typically reside under @file{/lib/sxemacs} +typically reside under @file{/share/sxemacs}. Where you'll find +the site's package lisp (@code{late-packages}). @item architecture-specific @cindex architecture-specific directories directories are specific both to the version of SXEmacs and the architecture it runs on and typically reside under -@file{/lib/sxemacs-/}. +@file{/lib/sxemacs-/}. This is where +you'll find the @dfn{emodules}, and other miscellaneous things such as +@code{gnuserv}, and @code{yow}. @end table -During installation, all of these directories may also reside directly -under @file{}, because that is where they are in the SXEmacs tarball. - If SXEmacs runs with the @code{-debug-paths} option (@pxref{Command Switches}), it will print the values of these variables, hopefully aiding in debugging any problems which come up.