# Module `package`

The package library provides basic facilities for loading and building modules in Lua.

It exports two of its functions directly in the global environment require and module. Everything else is exported in a table package.

## Type `package`

package.config | A string describing some compile-time configurations for packages.
package.cpath | The path used by require to search for a C loader.
package.loaded | A table used by `require` to control which modules are already loaded.
package.loaders | A table used by `require` to control how to load modules.
package.loadlib(libname, funcname) | Dynamically links the host program with the C library `libname`.
package.path | The path used by `require` to search for a Lua loader.
package.preload | A table to store loaders for specific modules (see `require`).
package.searchers | A table used by `require` to control how to load modules.
package.searchpath(name, path, name) | Sets a metatable for `module` with its `__index` field referring to the global environment, so that this module inherits values from the global environment.

## Type `package`

### Field(s)

#string package.config

  A string describing some compile-time configurations for packages.

  This string is a sequence of lines: * The first line is the directory separator string. Default is '' for Windows and '/' for all other systems. * The second line is the character that separates templates in a path. Default is ';'. * The third line is the string that marks the substitution points in a template. Default is '?'. * The fourth line is a string that, in a path in Windows, is replaced by the executable's directory. Default is '!'. * The fifth line is a mark to ignore all text before it when building the luaopen_ function name. Default is '-'.

#string package.cpath

  The path used by require to search for a C loader.

  Lua initializes the C path `package.cpath` in the same way it initializes the Lua path package.path, using the environment variable `LUA_CPATH_5_2` or the environment variable `LUA_CPATH` or a default path defined in `luaconf.h`.

#table package.loaded

  A table used by `require` to control which modules are already loaded.

  When you require a module `modname` and `package.loaded[modname]` is not false, `require` simply returns the value stored there.

#table package.loaders

  A table used by `require` to control how to load modules.

  Each entry in this table is a searcher function. When looking for a module, `require` calls each of these searchers in ascending order, with the module name (the argument given to `require`) as its sole parameter. The function can return another function (the module loader) or a string explaining why it did not find that module (or nil if it has nothing to say). Lua initializes this table with four functions.

  The first searcher simply looks for a loader in the `package.preload` table.

  The second searcher looks for a loader as a Lua library, using the path stored at `package.path`. A path is a sequence of templates separated by semicolons. For each template, the searcher will change each interrogation mark in the template by `filename`, which is the module name with each dot replaced by a "directory separator" (such as "`/`" in Unix); then it will try to open the resulting file name. So, for instance, if the Lua path is the string

      "./?.lua;./?.lc;/usr/local/?/init.lua"

  the search for a Lua file for module `foo` will try to open the files `./foo.lua`, `./foo.lc`, and `/usr/local/foo/init.lua`, in that order.

  The third searcher looks for a loader as a C library, using the path given by the variable `package.cpath`. For instance, if the C path is the string

      "./?.so;./?.dll;/usr/local/?/init.so"

  the searcher for module `foo` will try to open the files `./foo.so`, `./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds a C library, this searcher first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside the library to be used as the loader. The name of this C function is the string "`luaopen_`" concatenated with a copy of the module name where each dot is replaced by an underscore. Moreover, if the module name has a hyphen, its prefix up to (and including) the first hyphen is removed. For instance, if the module name is `a.v1-b.c`, the function name will be `luaopen_b_c`.

  The fourth searcher tries an all-in-one loader. It searches the C path for a library for the root name of the given module. For instance, when requiring `a.b.c`, it will search for a C library for `a`. If found, it looks into it for an open function for the submodule; in our example, that would be `luaopen_a_b_c`. With this facility, a package can pack several C submodules into one single library, with each submodule keeping its original open function.

package.loadlib(libname, funcname)

  Dynamically links the host program with the C library `libname`.

  Inside this library, looks for a function `funcname` and returns this function as a C function. (So, `funcname` must follow the protocol (see `lua_CFunction`)).

  This is a low-level function. It completely bypasses the package and module system. Unlike `require`, it does not perform any path searching and does not automatically adds extensions. `libname` must be the complete file name of the C library, including if necessary a path and extension. `funcname` must be the exact name exported by the C library (which may depend on the C compiler and linker used).

  This function is not supported by ANSI C. As such, it is only available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn` standard).

  ### Parameters

  - `#string libname` : the complete file name of the C library.

  - `#string funcname` : the name of a function defined in the C library named `libname`.

#string package.path

  The path used by `require` to search for a Lua loader.

  At start-up, Lua initializes this variable with the value of the environment variable `LUA_PATH` or with a default path defined in `luaconf.h`, if the environment variable is not defined. Any "`;;`" in the value of the environment variable is replaced by the default path.

#table package.preload

  A table to store loaders for specific modules (see `require`).

  This variable is only a reference to the real table; assignments to this variable do not change the table used by require.

#table package.searchers

  A table used by `require` to control how to load modules.

  Each entry in this table is a `searcher function`. When looking for a module, `require` calls each of these searchers in ascending order, with the module name (the argument given to `require`) as its sole parameter. The function can return another function (the module `loader`) plus an extra value that will be passed to that loader, or a string explaining why it did not find that module (or nil if it has nothing to say).

  Lua initializes this table with four searcher functions. The first searcher simply looks for a loader in the `package.preload` table. The second searcher looks for a loader as a Lua library, using the path stored at `package.path`. The search is done as described in function `package.searchpath`.

  The third searcher looks for a loader as a C library, using the path given by the variable `package.cpath`. Again, the search is done as described in function `package.searchpath`. For instance, if the C path is the string

      ./?.so;./?.dll;/usr/local/?/init.so

  the searcher for module foo will try to open the files `./foo.so`, `./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds a C library, this searcher first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside the library to be used as the loader. The name of this C function is the string "luaopen_" concatenated with a copy of the module name where each dot is replaced by an underscore. Moreover, if the module name has a hyphen, its prefix up to (and including) the first hyphen is removed. For instance, if the module name is a.v1-b.c, the function name will be luaopenbc.

  The fourth searcher tries an `all-in-one loader`. It searches the C path for a library for the root name of the given module. For instance, when requiring a.b.c, it will search for a C library for a. If found, it looks into it for an open function for the submodule; in our example, that would be luaopenab_c. With this facility, a package can pack several C submodules into one single library, with each submodule keeping its original open function.

  All searchers except the first one (preload) return as the extra value the file name where the module was found, as returned by `package.searchpath`. The first searcher returns no extra value.

package.searchpath(name, path, name)

  Sets a metatable for `module` with its `__index` field referring to the global environment, so that this module inherits values from the global environment.

  To be used as an option to function `module`.

  ### Parameters

  - `#string name` :

  - `#string path` :

  - `#string name` :