# Get Started with the Module Framework

_This page helps you get started with the module framework in KDB-X._

Learn about:

- [Creating modules](#create-modules)
- [The `export` variable](#the-export-variable)
- [Local namespace](#local-namespace)
- [Search path](#search-path)
- [Module hierarchy](#module-hierarchy)
- [Using `use`](#use)

- [Module-relative file path](#module-relative-file-path)
- [Converting a legacy library to a module](#converting-a-legacy-library-to-a-module)

## Create modules

The minimum requirement you need for creating a module is defining a variable named [`export`](#the-export-variable) containing a dictionary of the public interface of the module. For example:
```q
export:([f:{x+1};g:{x*2}])
```

This creates a module with two functions, `f` and `g`.

To load the module, place it on the search path using an appropriate file name - as described in the [search path](#search-path) section below - then load it via the `use` function:
```q
// $QHOME/mod/foo/init.q
export:([f:{x+1};g:{x*2}])

// user
q)foo:use`foo
q)foo.f 10
11
q)foo.g 10
20
```

The `use` function returns the module's `export`, allowing it to be stored in a variable in the user code.

## The `export` variable

The basic `export` variable is a dictionary:
```q
export:([f:{x+1};g:{x*2}])
```

The definitions do not have to be inline - bracketed dictionary syntax allows for deriving the keys from the variable names:
```q
f:{x+1}
g:{x*2}
export:([f;g])
```

Alternatively, `export` can be a function that returns a dictionary:
```q
f:{x+1}
g:{x*2}
export:{([f;g])}
```

In binary modules, the equivalent is to export a function named `kexport` (the name is not `export` because that is a reserved word in C++) which constructs the dictionary, using [`dl`](../../ref/languages/capiref.md#dl-dynamic-link) to create the objects representing the module functions:
```q
K kexport(K x) {
    K names = ktn(KS,2);
    kS(names)[0] = ss("foo");
    kS(names)[1] = ss("bar");
    K fns = ktn(0,2);
    kK(fns)[0] = dl((void*)k_foo, 1);
    kK(fns)[1] = dl((void*)k_bar, 1);
    return xD(names, fns);
}
```

## Local namespace

Traditional libraries typically use global names, either directly or via [`\d`](../../ref/syscmds.md/#d-directory):
```q
// library
.foo.f:{x+1}
.foo.g:{x*2}

// user
.foo.f[3]+.foo.g[4]
```
```q
// library
\d .foo
f:{x+1}
g:{x*2}

// user
.foo.f[3]+.foo.g[4]
```

This is problematic because if two libraries decide to use the same namespace name, they will clash, which incentivizes the usage of long and/or nested namespace names to ensure unicity. Furthermore, the internal variables and functions of libraries are exposed to the user, breaking encapsulation.

In contrast, modules should not use absolute names for either variables or namespaces. During the loading of a module, its current namespace is switched to a module-specific namespace that it can use to store internal variables and functions:
```q
MULT:2 // private value
f:{x+1} // private function
g:{f[x]*MULT}
export:([g])
```

The idea behind encapsulation is that users of the module should not directly access or modify the internal functions and variables. Variables cannot be made public (if added to `export`, the user gets a copy, not a reference) - to allow accessing them, the module should provide getter/setter functions.
```q
// $QHOME/mod/foo/init.q
MULT:2 // private value
f:{x+1} // private function
g:{f[x]*MULT}
getMult:{MULT}
setMult:{MULT::x}
export:([g;getMult;setMult])

// user
q)foo:use`foo
q)foo.getMult[]
2
q)foo.g[10]
22
q)foo.setMult 5
q)foo.g[10]
55
```

### Self-reference

Sometimes it is necessary to refer to the namespace the module is defined in. This can be achieved using the built-in variables `.z.m` and `.z.M`. 

- `.z.m` refers to the namespace of the current module
- `.z.M` is a symbol containing the name of the namespace

Furthermore, any name can be added to `.z.M` as if it was a member of that namespace to generate a symbolic name under the module namespace. When used in functions, `.z.m` and `.z.M` retain the information about which module they were defined in, as opposed to changing the reference based on what the current module is.
```q
// $QHOME/mod/foo/init.q
// log:{-1 string[.z.P]," ",x}  // doesn't work, since log is a reserved name
.z.m.log:{-1 string[.z.P]," ",x}
disableLog:{.z.M.log set(::);}
f:{x+1}
// upd:{.z.m.log"updating";select f a from ([]a:1 2 3)}  // would look for `f` in the user's namespace
upd:{.z.m.log"updating";select .z.m.f a from ([]a:1 2 3)}
export:([disableLog;upd])

// user
q)foo:use`foo
q)foo.upd[]
2025.10.07D15:36:13.107844497 updating
a
-
2
3
4
q)f:{x+3}
q)foo.upd[]
2025.10.07D15:36:20.624211098 updating
a
-
2
3
4
q)foo.disableLog[]
q)foo.upd[]
a
-
2
3
4
```

`.z.m` is also useful for combining the contents of modules as opposed to forcing one module's exports to live under a single name:
```q
q).z.m,:use`foo
```

Names formed with `.z.M` can be passed into legacy APIs that require a global variable name as a symbol.
```q
q).timer.addTimer[.z.M.cleanup;01:00]
```

Outside a module, `.z.m` and `.z.M` refer to the default namespace (`.`).

The name `.z.m` can also be used in the [`\d`](../../ref/syscmds.md/#d-directory) command to create a child namespace within the module's namespace:
```q
\d .z.m.foo
```

## Search path

Loading modules supports specifying a search path. If not specified, the search path is `$QHOME/mod`. The path can be given as a colon-separated list in the environment variable `QPATH` (in the same manner as the UNIX `PATH` variable), or at run time in the variable `.Q.m.SP` which contains a string list.

When loading a module `foo`, it is searched in turn at every element of the search path using the following file names for the case where `.Q.m.SP` contains only `"mp"`:
```q
  mp/foo.k
  mp/foo.q
  mp/foo.k_
  mp/foo.q_
  mp/foo.$PLATFORM.so
  mp/foo/init.k
  mp/foo/init.q
  mp/foo/init.k_
  mp/foo/init.q_
  mp/foo/init.$PLATFORM.so
```

In case there are multiple paths in `.Q.m.SP`, each path is checked for all of the above file names before moving on to the next path. The first matching file (in the order listed above) found will be used.

`$PLATFORM` is a platform identifier that consists of the operating system type (`w` for Windows, `l` for Linux and `m` for macOS), the architecture (`i` for Intel, `a` for ARM) and word size (`32` or `64`). For example, Linux on 64-bit Intel CPU is `li64`.

## Module hierarchy

It is possible for modules to refer to each other in a hierarchy. A name with a single leading period refers to a child, a name with two leading periods refers to a sibling, a name with three leading periods refers to a parent's sibling etc. It is also possible to refer to modules multiple levels down.

An example module tree:
```
$ tree $QHOME/mod
m
└── parent
    ├── child1.q
    ├── child2
    │   ├── grandchild1.q
    │   ├── grandchild2.q
    │   └── init.q
    └── init.q
```
```q
// $QHOME/mod/parent/init.q
-1"This is parent";
export:([])

// $QHOME/mod/parent/child1.q
-1"This is child1";
f:{"bbb",x}
export:([f])

// $QHOME/mod/parent/child2/init.q
-1"This is child2";
d:use`.grandchild1
f:{"ccc",d.f x}
export:([f])

// $QHOME/mod/parent/child2/grandchild1.q
-1"This is grandchild1";
e:use`..grandchild2
b:use`...child1
f:{"ddd",b.f e.f x}
export:([f])

// $QHOME/mod/parent/child2/grandchild2.q
-1"This is grandchild2";
f:{"eee",x}
export:([f])

// user
q)([f]):use`parent.child2
This is child2
This is grandchild1
This is grandchild2
This is child1
q)f"aaa"
"cccdddbbbeeeaaa"
```

## `use` 

As seen above, `use` returns the module's `export` such that it can be assigned to one or more variables in the user code. It also replaces any function definitions with aliases:
```q
q)f
`.m.parent.0child2.export.f[]
q)type f
104h
```

The alias refers to a generated name whose format should not be relied on. The advantage of using an alias is that if the underlying function changes (such as in the `.z.M.log set(::)` example above), the alias will automatically refer to the changed function, as opposed to retaining the previous value as with a plain assignment. 

To programmatically get the definition of the aliased function, use the following idiom:
```q
q)value first value f
{"ccc",d.f x}
```

`use` also deduplicates module loads. If a module is used multiple times, perhaps in different modules, it is only loaded once, and the subsequent `use` calls return a cached value.
```q
// fresh q session
q)f:use`parent.child1
This is child1
q)g:use`parent.child2
This is child2
This is grandchild1
This is grandchild2
// child1 is not loaded twice
```
<!--
`.Q.m.reuse` can be used to force a single module to be reloaded, but if it has any dependencies, those will still be retrieved from the cache.
```q
q)g:.Q.m.reuse`parent.child2
This is child2
```
//! add back in -->

Because it is a normal function, `use` can be used even inside functions, as long as the execution context has the necessary permissions (e.g. a function inside `peach` cannot load any new modules, but may retrieve an already loaded and cached module).
```q
q)f:{use[`parent.child1][`f]x}
q)f"aaa"
This is child1
"bbbaaa"
```

## Module-relative file path

A path starting with a double colon is relative to the path of the current module. Since path symbols also start with a colon, this means a module-relative path symbol has three colons. This resolution only works during module load. To use these paths in a function, resolve them at load time using `.Q.rp` and save the result in a variable.
```q
// $QHOME/mod/foo/init.q
\l ::bar.q
export:([f])

// $QHOME/mod/foo/bar.q
data:.Q.rp`:::bar.txt
f:{read0 data}

// $QHOME/mod/foo/bar.txt
hello world

// user
q)([f]):use`foo
q)f[]
"hello world"
```

## Converting a legacy library to a module

To convert an existing legacy library to a module, perform the following steps:

### q libraries

* If the module has any external dependencies, convert those to modules first, then replace the relevant import statements with `use`.
* Remove any absolute namespace name prefixes (e.g. `.lib.func` to `func`). This applies to all assignments, global variable references in functions, as well as `\d` commands (which should be removed if encompassing the entire module, or changed to use namespaces based on `.z.m`).
    * If removing the namespace prefix would create a conflict between a local and a global variable, change the global reference to use `.z.M` (although for code readability, renaming one of the two to be more distinct might be a better idea).
    * Assignments to globals in functions need to be switched from `:` to `::` to ensure the variable is still recognized as a global.
    * If a variable name would become invalid because of clashing with a reserved word (e.g. a function named `use`, `log` or `parse`), prefix it with `.z.m`.
    * Similarly, use the `.z.m` prefix for any global functions used by q-sql statements.
* Convert any relative paths to use the `::` prefix.
* Add an `export` global variable at the end of the module. This should be a dictionary containing the public interface of the module. For simple modules with no internal variables and functions, `export:.z.m` to export everything might suffice.
* Rename the module file to one of the file names supported by lookup (for a module `m`, this will typically be either `m.q` or `m/init.q`).
* In the user code, make sure that the path to the module is on `$QPATH`, and replace the import statement with `use`.

### Binary libraries

* Add a function named `kexport` that returns a dictionary containing the public interface functions of the module. See [the export variable](#the-export-variable) above for an example.
* Rename the library file to one of the file names supported by lookup (for a module `m` on Intel 64-bit Linux, this will typically be either `m.li64.so` or `m/init.li64.so`).
* In the user code, make sure that the path to the library is on `$QPATH`, and replace the import statement with `use`.
