Skip to content

Commit

Permalink
Move build_sysimg docstring
Browse files Browse the repository at this point in the history
This moves the docs for `build_sysimg` inline in `contrib/build_sysimg.jl`.
Adds an additional condition to the `build_sysimg.jl` file so that we
can safely include the file in `genstdlib.jl` without a system image being
built unintentionally.
  • Loading branch information
MichaelHatherly committed Jul 15, 2016
1 parent 6535f71 commit 32185da
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 5 deletions.
17 changes: 16 additions & 1 deletion contrib/build_sysimg.jl
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,18 @@ function default_sysimg_path(debug=false)
end
end

"""
build_sysimg(sysimg_path=default_sysimg_path, cpu_target="native", userimg_path=nothing; force=false)
Rebuild the system image. Store it in `sysimg_path`, which defaults to a file named `sys.ji`
that sits in the same folder as `libjulia.{so,dylib}`, except on Windows where it defaults
to `JULIA_HOME/../lib/julia/sys.ji`. Use the cpu instruction set given by `cpu_target`.
Valid CPU targets are the same as for the `-C` option to `julia`, or the `-march` option to
`gcc`. Defaults to `native`, which means to use all CPU instructions available on the
current processor. Include the user image file given by `userimg_path`, which should contain
directives such as `using MyPackage` to include that package in the new system image. New
system image will not replace an older image unless `force` is set to true.
"""
function build_sysimg(sysimg_path=nothing, cpu_target="native", userimg_path=nothing; force=false, debug=false)
if sysimg_path == nothing
sysimg_path = default_sysimg_path(debug)
Expand Down Expand Up @@ -157,7 +169,10 @@ end

# When running this file as a script, try to do so with default values. If arguments are passed
# in, use them as the arguments to build_sysimg above
if !isinteractive()
#
# Also check whether we are running `genstdlib.jl`, in which case we don't want to build a
# system image and instead only need `build_sysimg`'s docstring to be available.
if !isdefined(Main, :GenStdLib) && !isinteractive()
if length(ARGS) > 5 || ("--help" in ARGS || "-h" in ARGS)
println("Usage: build_sysimg.jl <sysimg_path> <cpu_target> <usrimg_path.jl> [--force] [--debug] [--help]")
println(" <sysimg_path> is an absolute, extensionless path to store the system image at")
Expand Down
7 changes: 3 additions & 4 deletions doc/devdocs/sysimg.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,9 @@ This will include a ``build_sysimg()`` function:

.. function:: build_sysimg(sysimg_path=default_sysimg_path, cpu_target="native", userimg_path=nothing; force=false)

Rebuild the system image. Store it in ``sysimg_path``, which defaults to a file named ``sys.ji`` that sits in the same folder as ``libjulia.{so,dylib}``, except on Windows where it defaults to ``JULIA_HOME/../lib/julia/sys.ji``.
Use the cpu instruction set given by ``cpu_target``. Valid CPU targets are the same as for the ``-C`` option to ``julia``, or the ``-march`` option to ``gcc``. Defaults to ``native``, which means to use all CPU instructions available on the current processor.
Include the user image file given by ``userimg_path``, which should contain directives such as ``using MyPackage`` to include that package in the new system image.
New system image will not replace an older image unless ``force`` is set to true.
.. Docstring generated from Julia source
Rebuild the system image. Store it in ``sysimg_path``\ , which defaults to a file named ``sys.ji`` that sits in the same folder as ``libjulia.{so,dylib}``\ , except on Windows where it defaults to ``JULIA_HOME/../lib/julia/sys.ji``\ . Use the cpu instruction set given by ``cpu_target``\ . Valid CPU targets are the same as for the ``-C`` option to ``julia``\ , or the ``-march`` option to ``gcc``\ . Defaults to ``native``\ , which means to use all CPU instructions available on the current processor. Include the user image file given by ``userimg_path``\ , which should contain directives such as ``using MyPackage`` to include that package in the new system image. New system image will not replace an older image unless ``force`` is set to true.

Note that this file can also be run as a script itself, with command line arguments taking the place of arguments passed to the ``build_sysimg`` function. For example, to build a system image in ``/tmp/sys.{so,dll,dylib}``, with the ``core2`` CPU instruction set, a user image of ``~/userimg.jl`` and ``force`` set to ``true``, one would execute:
::
Expand Down
4 changes: 4 additions & 0 deletions doc/genstdlib.jl
Original file line number Diff line number Diff line change
Expand Up @@ -200,4 +200,8 @@ validdocstr(other) = false

end

# The docstring for `build_sysimg` is defined is this file and included within the
# `devdocs/sysimg.rst` file, so we include it here to make it visible to the docsystem.
include(joinpath("..", "contrib", "build_sysimg.jl"))

GenStdLib.translate(["manual", "stdlib", "devdocs"])

0 comments on commit 32185da

Please sign in to comment.