===========================
 Custom Julia system image
===========================

.. versionadded:: 0.4

If you use standard ``julia`` program, the basic functionalities and
standard libraries of Julia are loaded from so called *system image*
file which contains the machine code compiled from the Julia code.
The Julia runtime can be configured to use a customized system image
which may contain non-standard packages.  This is a very effective way
to reduce startup time of complex Julia packages such as PyCall.
Furthermore, it can be used to workaround the problem in statically
linked Python executable if you have the problem described in
:ref:`statically-linked`.

How to use a custom system image
================================

To compile a custom system image for PyJulia, run

.. code-block:: console

   $ python3 -m julia.sysimage sys.so

where ``sys.dll`` and ``sys.dylib`` may be used instead of ``sys.so``
in Windows and macOS, respectively.

The command line interface `julia.sysimage` will:

* Install packages required for compiling the system image in an
  isolated Julia environment.
* Install PyCall to be compiled into the system image in an isolated
  Julia environment.
* Create the system image at the given path (``./sys.so`` in the above
  example).

To use this system image with PyJulia, you need to specify its path
using ``sysimage`` keyword argument of the `Julia` constructor.  For
example, if you run `python3` REPL at the directory where you ran the
above `julia.sysimage` command, you can do

>>> from julia import Julia
>>> jl = Julia(sysimage="sys.so")

to initialize PyJulia.  To check that this Julia runtime is using the
correct system image, look at the output of ``Base.julia_cmd()``

>>> from julia import Base
>>> Base.julia_cmd()
<PyCall.jlwrap `/PATH/TO/bin/julia-py -Cnative -J/PATH/TO/sys.so -g1`>


Limitations
===========

* ``PyCall`` and its dependencies cannot be updated after the system
  image is created.  A new system image has to be created to update
  those packages.

* The system image generated by `julia.sysimage` uses a different set
  of precompilation cache paths for each pair of ``julia-py``
  executable and the system image file.  Precompiled cache files
  generated by ``julia`` or a different ``julia-py`` executable cannot
  be reused by PyJulia when using the system image generated by
  `julia.sysimage`.

* The absolute path of ``julia-py`` is embedded in the system image.
  This system image is not usable if ``julia-py`` is removed.


Command line interfaces
=======================

``python3 -m julia.sysimage``
-----------------------------

.. automodule:: julia.sysimage
   :no-members:

``julia-py``
------------

.. automodule:: julia.julia_py
   :no-members: