Is it "safe" to link to libChakra.Jsrt.a?

[Fishrock123]

I'd like to link Chakra to use it via Rust, but Rust can't read headers so I need to get Symbols directly.

I see Symbols for all the APIs in the archive, but they all are prefixed by an underscore. Are these stable? Should I expect them to change or anything else?

[dilijev]

We export a flat C API to make it easy for other technologies to link against ChakraCore. The flat C API also avoids the name mangling that you would see with C++ symbols. You can consider the symbols exported as of any official ChakraCore release (e.g. release/1.2) to be stable -- and they will be maintained into the future.

The following is not guaranteed, but we also try our best to make sure any APIs that are added to master are maintained into the future. So, the short answer to your question is that you can consider any APIs in master to be reasonably safe to develop against, but technically the APIs added are subject to change up until an official release.

Since we don't have an official ChakraCore release yet, or have official Linux binaries for the release/1.2 branch, the best proxy you can use for exported symbols in that release is the ChakraCommon.h exports from the release/1.2 branch. You can also use the JSRT Reference which contains documentation for APIs which will be maintained into the future.

Note that we haven't made an official release yet, but if you wanted official Windows preview builds of release/1.2 for example, you can extract the binaries from our MyGet preview packages. Those packages are built from branch release/1.2, and the APIs exported in those binaries are not expected to change at this point.

I'm not sure what you mean by symbols prefixed with an underscore. Our flat-C-API function symbols should not be mangled by the compiler. What command are you using to list the symbols? I used readelf -Ws libChakra.Jsrt.a | grep -P "FUNC.*\bJs" and I see all of the JSRT API symbols like like the following lines (and have no leading underscores):

   160: 0000000000000760   366 FUNC    GLOBAL DEFAULT    2 JsAddRef
   161: 0000000000001230   220 FUNC    GLOBAL DEFAULT    2 JsBoolToBoolean
   162: 0000000000001310   102 FUNC    GLOBAL DEFAULT    2 JsBooleanToBool
   163: 0000000000008330   958 FUNC    GLOBAL DEFAULT    2 JsCallFunction
   164: 0000000000000550    27 FUNC    GLOBAL DEFAULT    2 JsCollectGarbage
   165: 00000000000086f0   952 FUNC    GLOBAL DEFAULT    2 JsConstructObject
   166: 0000000000001380   828 FUNC    GLOBAL DEFAULT    2 JsConvertValueToBoolean
   167: 0000000000001920   678 FUNC    GLOBAL DEFAULT    2 JsConvertValueToNumber
   168: 0000000000002920   678 FUNC    GLOBAL DEFAULT    2 JsConvertValueToObject
   169: 0000000000002090   689 FUNC    GLOBAL DEFAULT    2 JsConvertValueToString

/cc @digitalinfinity @jianchun @liminzhu

[ngsankha]

Yes, I had written bindings for ChakraCore to Rust (sankha93/ChakraCore.rs) and can confirm the names are not mangled by the compiler and it works.

[Fishrock123]

I was using nm BuildLinux/Test/lib/Jsrt/libChakra.Jsrt.a

Using wc -l on that, apparently there are 76756 symbols haha.

I do see a bunch of stuff like this in there, though only with the underscore.

0000000000001090 T _JsAddRef
0000000000001eb0 T _JsBoolToBoolean
0000000000002110 T _JsBooleanToBool
000000000000a630 T _JsCallFunction
0000000000000e10 T _JsCollectGarbage
000000000000a650 T _JsConstructObject
0000000000002180 T _JsConvertValueToBoolean
0000000000002850 T _JsConvertValueToNumber
0000000000003bd0 T _JsConvertValueToObject
0000000000003170 T _JsConvertValueToString
0000000000006e50 T _JsCreateArray

Also, it shows up twice.

[Fishrock123]

I don't seem to have readelf on OS X though.

[obastemur]

@Fishrock123 libChakra.Jsrt.a is not enough. See https://github.com/Microsoft/ChakraCore/blob/master/bin/ch/CMakeLists.txt#L41-L72

[Fishrock123]

@obastemur Sorry, I don't really understand what that linked code means.

I am not hugely familiar with C code so my knowledge goes as far as "there should be a (bunch of) .a and/or .o file(s) I need to link to". :/

[dilijev]

@obastemur @liminzhu It might be worth explicitly documenting in the Wiki how to link against the static or dynamic Linux libraries, since at the moment I think all of our instructions about linking are Windows-specific.

[obastemur]

@Fishrock123 if you are comfortable with Makefile ?

https://github.com/Microsoft/Chakra-Samples/tree/master/ChakraCore%20Samples/Hello%20World/Linux_OSX

[Fishrock123]

@obastemur Somewhat... are you saying what I need are these files?

LDIR=$(LIBRARY_PATH)/../pal/src/libChakra.Pal.a \
     $(LIBRARY_PATH)/Common/Core/libChakra.Common.Core.a \
     $(LIBRARY_PATH)/Jsrt/libChakra.Jsrt.a

[obastemur]

Exactly + if you have /usr/local/opt/icu4c/include folder as an --icu argument, you also need the libs below;

/usr/local/opt/icu4c/lib/libicudata.a
/usr/local/opt/icu4c/lib/libicuuc.a
/usr/local/opt/icu4c/lib/libicui18n.a 

[Fishrock123]

It would definitely be helpful if this were better documented.

I may be able to (help) do that if someone can point me to where that documentation should go.

[dilijev]

@Fishrock123 We take PRs to the Wiki :) https://github.com/Microsoft/ChakraCore-wiki

The new documentation would probably go here:

https://github.com/Microsoft/ChakraCore/wiki/Embedding-ChakraCore#linuxos-x

[dilijev]

@Fishrock123 @liminzhu @obastemur I opened an issue re: the documentation at microsoft/ChakraCore-wiki#8.

Closing this question as answered.

[Fishrock123]

@sankha93 & @obastemur I'm still having trouble linking it...

Getting this from cargo:

error: could not find native static library `ChakraCore`, perhaps an -L flag is missing?
error: Could not compile `rustyduk-nucleus`.

my Build.rs has the following instructions in it:

let lib_path = "deps/ChakraCore/BuildLinux/Test/lib/";


println!("cargo:rustc-link-search=native={}{}", lib_path,
         "../pal/src/libChakra.Pal.a");

println!("cargo:rustc-link-search=native={}{}", lib_path,
         "Common/Core/libChakra.Common.Core.a");

println!("cargo:rustc-link-search=native={}{}", lib_path,
         "Jsrt/libChakra.Jsrt.a");

println!("cargo:rustc-link-lib=static=ChakraCore");

Note: cargo:rustc-link-search= tell rustc to pass the following statement to as -L ... so I must have the wrong name in cargo:rustc-link-lib=static=ChakraCore but I can't tell what it would be.

The previous Rust bindings are windows only and use ChakraCore .. but I'm on OS X...

Compile instructions:

deps/ChakraCore/build.sh --static --test-build --icu=/usr/local/opt/icu4c/include -j=8

[Fishrock123]

Looks like that was a rustc linking problem.

e.g. this is the correct way:

println!("cargo:rustc-link-search=native={}{}", lib_path, "Jsrt/");
println!("cargo:rustc-link-lib=static=Chakra.Jsrt");

Now I'm getting a ton of Symbol errors from clang though, even though I've also linked the icu libraries... https://gist.github.com/Fishrock123/78cefc176bfc6f87bef99a32dd965fc1

[Fishrock123]

Update, linked CoreFoundation and Security frameworks, took the Symbols errors down a bit but not completely: https://gist.github.com/Fishrock123/a91ae0cb85041d5ebf45b18d08a868b9

[obastemur]

@Fishrock123 looks like it is because of std lib references.

[Fishrock123]

@obastemur Is that something that needs to be fixed here?

I'll try on Linux in a day or two.

OS X 10.10.5 fwiw

[dilijev]

@Fishrock123 OS X 10.10.5 should work, since we support 10.9+ but if we experience problems specifically because of that then I'd say there's a compat bug. For now let's assume it's not because of OS version.

[obastemur]

The problem that I can see there is missing std lib references. This happens due to targeting different lib mostly. i.e. ChakraCore is built against your OS SDK while Rust targets a much older SDK.

[dilijev]

@obastemur is it possible to build Rust with the newer SDK or ChakraCore with the Rust version of the SDK? (Which of these options is more difficult?)

[obastemur]

@dilijev IMO we will target a bit earlier version of macOS SDK (also for node-chakracore). Will work on this.

[dilijev]

@obastemur @Fishrock123 can we open a separate work item to resolve this issue and close this Question?

[Fishrock123]

@dilijev that's cool with me, so long as it is tracked, whatever suits your workflow best.

[dilijev]

Opened #1492 to track SDK issue.