The Common Lisp package is organized into four main files:
This is the main file, which contains basic functions and information about the package. This file is relatively compact.
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.
This file contains most of the advanced functions for operating
on sequences or lists, such as cl-delete-if and cl-assoc.
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.
See Obsolete Features.
The old file cl.el, as well as the even older cl-compat.el, are deprecated and will be removed in a future version of Emacs. Any existing code that uses them should be updated to use cl-lib.el instead.