Generate system image with PyCall in "PyJulia-mode"

docs/source/index.md

@@ -24,6 +24,7 @@ PyJulia is tested against Python versions 2.7, 3.5, 3.6, and 3.7.
    usage
    troubleshooting
    api
+   sysimage
    pytest
    how_it_works
    limitations

docs/source/limitations.md

@@ -21,7 +21,7 @@ example, the Julia method `sum!` can be called in PyJulia using
 There was a major overhaul in the module loading system between Julia
 0.6 and 1.0.  As a result, the "hack" supporting the PyJulia to load
 PyCall stopped working.  For the implementation detail of the hack,
-see: <https://github.com/JuliaPy/pyjulia/tree/master/julia/fake-julia>
+see: <https://github.com/JuliaPy/pyjulia/tree/v0.3.0/src/julia/fake-julia>
 
 For the update on this problem, see:
 <https://github.com/JuliaLang/julia/issues/28518>

docs/source/sysimage.rst

@@ -0,0 +1,85 @@
+===========================
+ 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: