Merge pull request #4 from vdods/master

Added demonstration of linking Rust lib statically

Author: mediremi

.gitignore

@@ -0,0 +1,2 @@
+main_shared
+main_static

Makefile

@@ -1,9 +1,38 @@
 ROOT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
 
-build:
+# PHONY means that it doesn't correspond to a file; it always runs the build commands.
+
+.PHONY: build-all
+build-all: build-shared build-static
+
+.PHONY: run-all
+run-all: run-shared run-static
+
+.PHONY: build-shared
+build-shared:
 cd lib/hello && cargo build --release
 cp lib/hello/target/release/libhello.so lib/
-go build -ldflags="-r $(ROOT_DIR)lib" main.go
+go build -ldflags="-r $(ROOT_DIR)lib" main_shared.go
+
+.PHONY: build-static
+build-static:
+cd lib/hello && cargo build --release
+cp lib/hello/target/release/libhello.a lib/
+go build main_static.go
+
+.PHONY: run-shared
+run-shared:
+RUST_LOG=trace ./main_shared
+
+.PHONY: run-static
+run-static:
+RUST_LOG=trace ./main_static
+
+# This is just for running the Rust lib tests natively via cargo.
+.PHONY: test-rust-lib
+test-rust-lib:
+cd lib/hello && RUST_LOG=trace cargo test -- --nocapture
 
-run: build
-./main
+.PHONY: clean
+clean:
+rm -rf main_shared main_static lib/libhello.so lib/libhello.a lib/hello/target

README.md

@@ -1,13 +1,16 @@
 # Rust + Golang
 ---
 
-This repository shows how, by combining
-[`cgo`](https://blog.golang.org/c-go-cgo) and
-[Rust's FFI capabilities](https://doc.rust-lang.org/book/ffi.html), we can call
+This repository shows how, by combining [`cgo`](https://blog.golang.org/c-go-cgo)
+and [Rust's FFI capabilities](https://doc.rust-lang.org/book/ffi.html), we can call
 Rust code from Golang.
 
-Run `make build` and then `./main` to see `Rust` + `Golang` in action. You
-should see `Hello John Smith!` printed to `stdout`.
+Run `make build-all` and then `make run-all` to see `Rust` + `Golang` in action,
+building and running two binaries, one where the Rust lib is compiled to a shared
+lib, and one to a static lib. You should see some log output printed to stderr and
+then `Hello John Smith!` printed to `stdout`. This results in the binaries
+`main_shared` and `main_static` which you can run. See [Makefile](Makefile) in
+this repository for more useful make targets.
 
 ## You can do this for your own project
 Begin by creating a `lib` directory, where you will keep your Rust libraries.
@@ -19,6 +22,8 @@ types that you used.
 All that is left to do is to add some `cgo`-specific comments to your Golang
 code. These comments tell `cgo` where to find the library and its headers.
 
+For importing a shared lib into your go code, the following must go along with an
+additional option given to `go build` (see Makefile):
 ```go
 /*
 #cgo LDFLAGS: -L./lib -lhello
@@ -27,7 +32,15 @@ code. These comments tell `cgo` where to find the library and its headers.
 import "C"
 ```
 
-> There should not be a newline between `*/` and `import "C"`.
+For a static lib, the additional `-ldl` is necessary compared to the shared
+lib, presumably because in the shared lib linking, `dl` is linked in some other way
+by the magic of shared libs. To import a static lib into your go code:
+```
+/*
+#cgo LDFLAGS: ./lib/libhello.a -ldl
+#include "./lib/hello.h"
+*/
+import "C"
+```
 
-A simple `make build` (use the [Makefile](Makefile) in this repository) will
-result in a binary that loads your dynamic library.
+> There should not be a newline between `*/` and `import "C"`.

lib/.gitignore

@@ -0,0 +1,2 @@
+libhello.a
+libhello.so

lib/hello.h

@@ -1 +1,5 @@
+// NOTE: You could use https://michael-f-bryan.github.io/rust-ffi-guide/cbindgen.html to generate
+// this header automatically from your Rust code. But for now, we'll just write it by hand.
+
+void init_stuff();
 void hello(char *name);

lib/hello/.gitignore

@@ -0,0 +1,2 @@
+Cargo.lock
+target

lib/hello/Cargo.toml

@@ -3,7 +3,12 @@ name = "hello"
 version = "0.1.0"
 
 [lib]
-crate-type = ["cdylib"]
+# If you only wanted shared lib, you'd use only "cdylib".
+# If you only wanted static lib, you'd use only "staticlib".
+# This demo shows both.
+crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
 libc = "0.2.2"
+env_logger = "0.8.4"
+log = "0.4.14"

lib/hello/src/lib.rs

@@ -1,9 +1,35 @@
-extern crate libc;
 use std::ffi::CStr;
 
+#[no_mangle]
+pub extern "C" fn init_stuff() {
+ env_logger::init();
+
+ log::trace!("init_stuff() trace level message");
+ log::debug!("init_stuff() debug level message");
+ log::info!("init_stuff() info level message");
+ log::warn!("init_stuff() warn level message");
+ log::error!("init_stuff() error level message");
+}
+
 #[no_mangle]
 pub extern "C" fn hello(name: *const libc::c_char) {
  let buf_name = unsafe { CStr::from_ptr(name).to_bytes() };
  let str_name = String::from_utf8(buf_name.to_vec()).unwrap();
  println!("Hello {}!", str_name);
 }
+
+// This is present so it's easy to test that the code works natively in Rust via `cargo test
+#[cfg(test)]
+pub mod test {
+
+ use std::ffi::CString;
+ use super::*;
+
+ // This is meant to do the same stuff as the main function in the .go files.
+ #[test]
+ fn simulated_main_function () {
+ init_stuff();
+ hello(CString::new("John Smith").unwrap().into_raw());
+ }
+
+}

main.go renamed to main_shared.go

@@ -1,11 +1,14 @@
 package main
 
+// NOTE: There should be NO space between the comments and the `import "C"` line.
+
 /*
 #cgo LDFLAGS: -L./lib -lhello
 #include "./lib/hello.h"
 */
 import "C"
 
 func main() {
+ C.init_stuff()
 C.hello(C.CString("John Smith"))
 }

main_static.go

@@ -0,0 +1,15 @@
+package main
+
+// NOTE: There should be NO space between the comments and the `import "C"` line.
+// The -ldl is necessary to fix the linker errors about `dlsym` that would otherwise appear.
+
+/*
+#cgo LDFLAGS: ./lib/libhello.a -ldl
+#include "./lib/hello.h"
+*/
+import "C"
+
+func main() {
+ C.init_stuff()
+C.hello(C.CString("John Smith"))
+}