24.3. Function REQUIRE

24.3.1. Return value
24.3.2. Additional LOAD locations
24.3.4. Interaction with COMPILE-FILE

The function REQUIRE receives as the optional argument either a PATHNAME or a LIST of PATHNAMEs: files to be LOADed if the required module is not already present.

24.3.1. Return value

When the module is already present, NIL is returned; otherwise returns the TRUENAME which was loaded to satisfy the REQUIREment (or LIST thereof iff the second argument is a LIST).

24.3.2. Additional LOAD locations

In addition to (and before) CUSTOM:*LOAD-PATHS*, REQUIRE tries to find the file to LOAD in the following locations:

When REQUIRE is called without the second (pathname) argument, the elements of the CUSTOM::*MODULE-PROVIDER-FUNCTIONS* LIST are called one by one on the first (module name) argument until one of them returns non-NIL. If all of them return NIL, LOAD is called as described above.

Initially the lisp is empty; (require "asdf") modifies it (Platform Dependent: if CLISP was configured with the option --with-module=asdf).

24.3.4. Interaction with COMPILE-FILE

At compile time, (REQUIRE #P"foo") forms are treated specially: CUSTOM:*LOAD-PATHS* is searched for #P"foo.lisp" and #P"foo.lib". If the latest such file is a #P".lisp", it is compiled; otherwise the #P".lib" is loaded. If neither is found, (REQUIRE #P"foo") is called.


It is a very bad idea to name your files the same way as CLISP modules (whether system-supplied or user-installed) because then REQUIRE will use different files at compile and execution times.

The #P".lib" is a header file which contains the constant, variable, inline and macro definitions necessary for compilation of the files that REQUIRE this file, but not the function definitions and calls that are not necessary for that. Thus it is not necessary to either enclose REQUIRE forms in EVAL-WHEN or to load the required files in the makefiles: if you have two files, #P"foo.lisp" and #P"bar.lisp", and the latter requires the former, you can write in your Makefile:

all: foo.fas bar.fas

foo.fas: foo.lisp
	clisp -c foo

bar.fas: bar.lisp foo.fas
	clisp -c bar

instead of the more cumbersome (and slower, since #P".lib"s are usually smaller and load faster that #P".fas"s):

bar.fas: bar.lisp foo.fas
        clisp -i foo -c bar

Thus, you do not need to (LOAD #P"foo") in order to (COMPILE-FILE #P"bar.lisp"). If memory is tight, and if #P"foo.lisp" contains only a few inline functions, macros, constants or variables, this is a space and time saver. If #P"foo.lisp" does a lot of initializations or side effects when being loaded, this is important as well.

These notes document CLISP version 2.49+Last modified: 2016-09-05