** 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
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.
* 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
----------------------
-.TH SXEMACS 1 "2007-12-29"
+.TH SXEMACS 1 "2015-06-05"
.UC 4
.SH NAME
sxemacs \- Emacs Redefined
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
.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.
\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
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
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
@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.
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.
@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}
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{<root>/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{<root>/lib/sxemacs-<VERSION>} 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{<root>/lib/sxemacs-<VERSION>} 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
@item version-specific
@cindex version-specific directories
directories are specific to the version of SXEmacs they belong to and
-typically reside under @file{<root>/lib/sxemacs-<VERSION>}.
+typically reside under @file{<root>/share/sxemacs-<VERSION>}. 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{<root>/lib/sxemacs}
+typically reside under @file{<root>/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{<root>/lib/sxemacs-<VERSION>/<ARCHITECTURE>}.
+@file{<root>/lib/sxemacs-<VERSION>/<ARCHITECTURE>}. 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{<root>}, 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.
projects / sxemacs / commitdiff