cl: Organization
1.2 Organization
================
The Common Lisp package is organized into four main files:
‘cl-lib.el’
This is the main file, which contains basic functions and
information about the package. This file is relatively compact.
‘cl-extra.el’
This file contains the larger, more complex or unusual functions.
It is kept separate so that packages which only want to use Common
Lisp fundamentals like the ‘cl-incf’ function won’t need to pay the
overhead of loading the more advanced functions.
‘cl-seq.el’
This file contains most of the advanced functions for operating on
sequences or lists, such as ‘cl-delete-if’ and ‘cl-assoc’.
‘cl-macs.el’
This file contains the features that are macros instead of
functions. Macros expand when the caller is compiled, not when it
is run, so the macros generally only need to be present when the
byte-compiler is running (or when the macros are used in uncompiled
code). Most of the macros of this package are isolated in
‘cl-macs.el’ so that they won’t take up memory unless you are
compiling.
The file ‘cl-lib.el’ includes all necessary ‘autoload’ commands for
the functions and macros in the other three files. All you have to do
is ‘(require 'cl-lib)’, and ‘cl-lib.el’ will take care of pulling in the
other files when they are needed.
There is another file, ‘cl.el’, which was the main entry point to
this package prior to Emacs 24.3. Nowadays, it is replaced by
‘cl-lib.el’. The two provide the same features (in most cases), but use
different function names (in fact, ‘cl.el’ mainly just defines aliases
to the ‘cl-lib.el’ definitions). Where ‘cl-lib.el’ defines a function
called, for example, ‘cl-incf’, ‘cl.el’ uses the same name but without
the ‘cl-’ prefix, e.g., ‘incf’ in this example. There are a few
exceptions to this. First, functions such as ‘cl-defun’ where the
unprefixed version was already used for a standard Emacs Lisp function.
In such cases, the ‘cl.el’ version adds a ‘*’ suffix, e.g., ‘defun*’.
Second, there are some obsolete features that are only implemented in
‘cl.el’, not in ‘cl-lib.el’, because they are replaced by other standard
Emacs Lisp features. Finally, in a very few cases the old ‘cl.el’
versions do not behave in exactly the same way as the ‘cl-lib.el’
versions. 
Obsolete Features.
Since the old ‘cl.el’ does not use a clean namespace, Emacs has a
policy that packages distributed with Emacs must not load ‘cl’ at run
time. (It is ok for them to load ‘cl’ at _compile_ time, with
‘eval-when-compile’, and use the macros it provides.) There is no such
restriction on the use of ‘cl-lib’. New code should use ‘cl-lib’ rather
than ‘cl’.
There is one more file, ‘cl-compat.el’, which defines some routines
from the older Quiroz ‘cl.el’ package that are not otherwise present in
the new package. This file is obsolete and should not be used in new
code.
Info Catalog
cl: Usage
cl: Overview
cl: Naming Conventions