Merge pull request #10069 from waTeim/waT/jconfig

Add a julia-config script for configuration of externals

Makefile

@@ -304,6 +304,8 @@ endif
 	$(INSTALL_M) contrib/build_sysimg.jl $(DESTDIR)$(datarootdir)/julia/
 	# Copy in standalone executable build script
 	$(INSTALL_M) contrib/build_executable.jl $(DESTDIR)$(datarootdir)/julia/
+	# Copy in standalone julia-config script
+	$(INSTALL_M) contrib/julia-config.jl $(DESTDIR)$(datarootdir)/julia/
 	# Copy in all .jl sources as well
 	cp -R -L $(build_datarootdir)/julia $(DESTDIR)$(datarootdir)/
 	# Copy documentation

contrib/julia-config.jl

@@ -0,0 +1,64 @@
+#!/usr/bin/env julia
+
+const options =
+[
+    "--cflags",
+    "--ldflags",
+    "--ldlibs"
+];
+
+function imagePath()
+    opts = Base.JLOptions();
+    bytestring(opts.image_file);
+end
+
+function libDir()
+    abspath(dirname(Sys.dlpath("libjulia")));
+end
+
+function includeDir()
+    joinpath(match(r"(.*)(bin)",JULIA_HOME).captures[1],"include","julia");
+end
+
+function initDir()
+    @unix_only return match(r"(.*)(/julia/sys.ji)",imagePath()).captures[1];
+    @windows_only return match(r"(.*)(\\julia\\sys.ji)",imagePath()).captures[1];
+end
+
+function ldflags()
+    replace("""-L$(libDir())""","\\","\\\\");
+end
+
+function ldlibs()
+    @unix_only return replace("""-Wl,-rpath,$(libDir()) -ljulia""","\\","\\\\");
+    @windows_only return replace("""-ljulia""","\\","\\\\");
+end
+
+function cflags()
+    arg1 = replace(initDir(),"\\","\\\\\\\\");
+    arg2 = replace(includeDir(),"\\","\\\\");
+    return """-DJULIA_INIT_DIR=\\"$arg1\\" -I$arg2""";
+end
+
+function check_args(args)
+    checked = intersect(args,options);
+    if length(checked) == 0 || length(checked) != length(args)
+        println(STDERR,"Usage: julia-config [",reduce((x,y)->"$x|$y",options),"]");
+        exit(1);
+    end
+end
+
+function main()
+    check_args(ARGS);
+    for args in ARGS
+        if args == "--ldflags"
+            println(ldflags());
+        elseif args == "--cflags"
+            println(cflags());
+        elseif args == "--ldlibs"
+            println(ldlibs());
+        end
+    end
+end
+
+main();

doc/manual/embedding.rst

@@ -45,6 +45,59 @@ The second statement in the test program evaluates a Julia statement using a cal
 
 Before the program terminates, it is strongly recommended to call ``jl_atexit_hook``.  The above example program calls this before returning from ``main``.
 
+## Using julia-config to automatically determine build parameters
+
+The script *julia-config.jl* was created to aid in determining what build parameters are required by a program that uses embedded Julia.  This script uses the
+build parameters and system configuration of the particular Julia distribution it is invoked by to export the necessary compiler flags for an embedding program to
+interact with that distribution.  This script is located in the Julia shared data directory.
+
+### Example
+
+Below is essentially the same as above with one small change; the argument to ``jl_init`` is now **JULIA_INIT_DIR** which is defined by *julia-config.jl*.
+
+    #include <julia.h>
+
+    int main(int argc, char *argv[])
+    {
+       jl_init(JULIA_INIT_DIR);
+       (void)jl_eval_string("println(sqrt(2.0))");
+       jl_atexit_hook();
+       return 0;
+    }
+
+
+### On the command line
+
+A simple use of this script is from the command line.  Assuming that *julia-config.jl* is located in */usr/local/julia/share/julia*, it can be invoked on
+the command line directly and takes any combination of 3 flags
+
+    /usr/local/julia/share/julia/julia-config.jl
+    Usage: julia-config [--cflags|--ldflags|--ldlibs]
+
+If the above example source is saved in the file *embed_exmaple.c*, then the following command will compile it into a running program on Linux and Windows (MSYS2 environment),
+or if on OS/X, then substitute clang for gcc.
+
+    /usr/local/julia/share/julia/julia-config.jl --cflags --ldflags --ldlibs | xargs gcc embed_example.c
+
+### Use in Makefiles
+
+But in general, embedding projects will be more complicated than the above, and so the following allows general makefile support as well -- assuming GNU make because
+of the use of the **shell** macro expansions.  Additionally, though many times *julia-config.jl* may be found in the directory */usr/local*, this is not necessarily the case,
+but Julia can be used to locate *julia-config.jl* too, and the makefile can be used to take advantage of that.  The above example is extended to use a Makefile
+
+Makefile:
+
+    JL_SHARE = $(shell julia -e 'print(joinpath(JULIA_HOME,Base.DATAROOTDIR,"julia"))')
+    CFLAGS   += $(shell $(JL_SHARE)/julia-config.jl --cflags)
+    CXXFLAGS += $(shell $(JL_SHARE)/julia-config.jl --cflags)
+    LDFLAGS  += $(shell $(JL_SHARE)/julia-config.jl --ldflags)
+    LDLIBS   += $(shell $(JL_SHARE)/julia-config.jl --ldlibs)
+
+    all: embed_example
+
+Now the build command is simply **make**.
+
+
 Converting Types
 ========================