Modules

Namespace management refers to the language’s capabilities to make names in a module available in other modules. Related concepts and functionality will be discussed in detail below.

Modules can contain modules in which the same syntax module …​ end+ is nested. They can be used to introduce separate namespaces, which can be useful for organizing complex code bases. Note that each module introduces its own scope, so submodules do not automatically inherit names from their parent module.

It is recommended that submodules refer to other modules within the enclosing parent module (including the last one) using the _ relative module qualifiers in the using and import statements. The relative module qualifier starts with a dot (.), which corresponds to the current module, and each subsequent character is . leads to the parent module of the current module. It should be followed by modules, if necessary, and eventually the actual name to be accessed. All elements are separated by the . symbol.

Consider the following example, where the submodule SubA defines a function, which is then expanded in its single-level module:

You can see the code in the packages, which in a similar situation uses

However, it works through code download and therefore only works if the `ParentModule' module is in the package. It is recommended to use relative paths.

Note that when calculating values, the order of definitions is also important. Consider

where the Sub module tries to use the TestPackage' variable.y before it was defined, so it has no value.

For similar reasons, it is not possible to use cyclic ordering.

It can take several seconds to load large modules, as it often requires a significant amount of code to compile in order to execute all the statements in a module. To reduce this time, Julia creates precompiled module caches.

When loading a module using the import or using operator, precompiled module files (sometimes called "cache files") are automatically created and used. If there are no cache files yet, the module will be compiled and saved for future reuse. To create these files without loading the module, you can also call Base.compilecache(Base.identify_package("modulename")) manually. The resulting cache files will be saved in the compiled subfolder in the DEPOT_PATH[1] folder. If nothing has changed in your system, these cache files will be used when loading the module using the import or using operator.

Precompiled files contain definitions of modules, types, methods, and constants. They can also contain method specializations and code created for them, but usually the developer must explicitly add directives for this. precompile or perform workloads that force compilation during package build.

However, if you update the module’s dependencies or change its source code, the module will be automatically recompiled when using the using or import operator. Dependencies are imported modules, the Julia build, included files, or explicit dependencies declared using a function. include_dependency(path) in the module files.

For file dependencies uploaded using include, the change is determined by analyzing whether the file size (fsize) or its contents (compressed into a hash) are unchanged. For file dependencies loaded using include_dependency, the change is determined by analyzing whether the modification time (mtime) is unchanged or equal to the modification time truncated to the nearest second (for systems that cannot copy mtime with precision in fractions of a second). It also takes into account whether the file path selected by the search logic in require matches the path used to create the pre-compilation file. In addition, a set of dependencies already loaded into the current process is taken into account. These modules will not be recompiled, even if their files change or disappear, to avoid incompatibilities between the running system and the pre-compilation cache. Finally, changes in any compile-time settings.

If it is known that the precompilation of a module is unsafe (for example, for one of the reasons described below), you must place the function __precompile__(false) in the module file (usually at the top). As a result, the Base.compilecache function will return an error, and the using or import operator will load the module directly into the current process and skip the pre-compilation and caching procedures. It also prevents the module from being imported by any other precompiled module.

You may need to be aware of some of the behavioral features inherent in creating additional shared libraries that require attention when writing a module. For example, the external state is not saved. To take this point into account, it is necessary to explicitly separate the initialization steps that must be performed during execution from the steps that may occur during compilation. To do this, Julia allows you to define the function __init__() in the module, which performs any initialization steps that should occur during execution. This function will not be called during compilation (--output-*). In fact, we can assume that it will be executed exactly once during the entire lifetime of the code. Of course, you can call it manually if necessary, but by default it is assumed that this function works with the computing state for the local computer, which does not need to be fixed in the compiled image. The function will be called after the module is loaded into the process, including if it is loaded into the incremental compilation process (--output-incremental=yes), but will not be called if the module is loaded into the full compilation process.

In particular, if you define the function function __init__() in the module, Julia will call the function __init__()`immediately _ after loading the module (for example, using the `import, using, or require statements) during execution for the first time (i.e., the function __init__ is called only once and only after executing all the statements in the module). Since the function is called after the module is fully imported, the functions of the __init__ submodules or other imported modules are called _ before the '__init__' function of the enclosing module.

Two typical uses of the __init__ function are calling the runtime initialization functions of external C libraries and initializing global constants, which use pointers returned by external libraries. For example, suppose you need to call the C library libfoo', for which you need to call the initialization function `foo_init() at runtime. Let’s assume that we should also preempt the global constant foo_data_ptr, which will store the return value of the void *foo_data() function defined by the libfoo library. This constant must be initialized at runtime (not at compile time), because the address of the pointer will change with each execution. This can be done by defining the following function in the module `__init__'.

Note that it is quite possible to define a global object inside a function of type __init__'. This is one of the advantages of using a dynamic language. By making an object a constant in the global scope, you can ensure that the type is known to the compiler and allow it to generate more optimized code. Obviously, any other global objects in the module that depends on `foo_data_ptr must also be initialized in the `__init__' function.

Constants associated with most Julia objects that are not created using a keyword 'ccall`, does not need to be placed in the function __init__': their definitions can be precompiled and loaded from the cached module image. These include complex heap-allocated objects such as arrays. However, any subroutine that returns the raw pointer value should be called at runtime, otherwise no precompilation will be performed (objects `Ptr will turn into null pointers unless they are hidden inside the object. isbits). This includes the return values of Julia functions. @cfunction and pointer.

The situation with dictionary types and set types, or in general with everything that depends on the output of the hash(key) method, is much more complicated. In general, when the keys are numbers, strings, symbols, ranges, Expr expressions, or compositions of these types (via arrays, tuples, sets, pairs, etc.), pre`compilation is performed without problems. However, for some other key types, such as Function or DataType, and universal user-defined types for which no hash method is defined, the backup hash method depends on the object’s memory address (via its objectid identifier) and, therefore, may change with each execution. If you have one of these types of keys or you are not sure, for security reasons, you can initialize this dictionary in the function __init__'. Alternatively, you can use a dictionary type. `IdDict, which is specially processed as part of pre-compilation so that it can be safely initialized during compilation.

When using precompilation, it is important to clearly understand the difference between the compilation stage and the execution stage. In this mode, it is often much more obvious that Julia is a compiler that allows arbitrary Julia code to be executed, rather than a separate interpreter that also generates compiled code.

Other known potential failure scenarios are listed below.:

julia mystdout = Base.stdout #= will not work correctly because Base.stdout will be copied to this module =

getstdout() = Base.stdout = best option =

init() = global mystdout = Base.stdout = also works =``

There are several additional restrictions for operations that can be performed during pre-compilation of the code, designed to help the user avoid other situations with incorrect behavior.

Below are a few more points that you should pay attention to.

Sometimes it is advisable to disable incremental pre-compilation during module development. You can enable or disable pre-compilation of a module using the command-line flag --compiled-modules={yes|no|existing}. When Julia is started with the --compiled-modules=no flag set, the serialized modules in the compilation cache are ignored when loading modules and module dependencies. In some cases, you may need to download existing precompiled modules, but not create new ones. This can be done by running Julia with --compiled-modules=existing'. More detailed control is provided by the `--pkgimages={yes|no|existing}, which only acts to store the machine code during pre-compilation. The Base.compilecache function can still be called manually. The status of this command line flag is passed to the 'Pkg' script.build` to disable the automatic start of pre-compilation when installing, updating, and explicitly building packages.

Some pre-compilation failures can also be debugged using environment variables. If you set `JULIA_VERBOSE_LINKING=true', it can help eliminate failures when linking shared libraries of compiled machine code. In the developer documentation in the Julia manual, there is a section on the features of the Julia internal device, in the chapter "Package Images", where you can find more detailed information.