reapi: updates for golang

Problem: Go bindings can be more friendly to Go developers
Solution: This includes docstring changes, the main module path
to be under flux-framework, returning Go error instead of int,
and updating tests to return nil (no error) instead of 0. The
module path is fixed from a development variant to a
flux-framework one. Finally, it fixes the Go bindings to
use a struct instead of passing around a ctx variable. Our
goal with these final changes to the Go module is to make
the code more friendly to future go developers.

Signed-off-by: vsoch <vsoch@users.noreply.github.com>

.devcontainer/Dockerfile

@@ -25,7 +25,7 @@ RUN sudo apt-get -qq install -y --no-install-recommends \
         curl
 
 # Assuming installing to /usr/local
-ENV LD_LIBRARY_PATH=/usr/local/lib
+ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
 
 RUN curl -s -L https://github.com/Kitware/CMake/releases/download/v3.26.4/cmake-3.26.4-linux-$(uname -m).sh > cmake.sh ;\
     sudo bash cmake.sh --prefix=/usr/local --skip-license ;\

.devcontainer/devcontainer.json

@@ -1,15 +1,17 @@
 {
-    "name": "Flux Sched Developer Environment",
-    "dockerFile": "Dockerfile",
-    "context": "../",
+  "name": "Flux Sched Developer Environment",
+  "dockerFile": "Dockerfile",
+  "context": "../",
 
-    "customizations": {
-      "vscode": {
-        "settings": {
-          "terminal.integrated.defaultProfile.linux": "bash"
-        }
-      }
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+  },
+      "extensions": [
+         "ms-vscode.cmake-tools"
+      ]
     }
   },
   "postStartCommand": "git config --global --add safe.directory /workspaces/flux-sched"
-}
+}

.gitignore

@@ -131,3 +131,6 @@ compile_flags.txt
 # Rules to ignore auto-generated test harness scripts
 test_*.t
 !/src/bindings/python/test_commands/test_runner.t
+
+# Go
+resource/reapi/bindings/go/src/test/main

CMakeLists.txt

@@ -174,6 +174,12 @@ if(ENABLE_COVERAGE)
   SET( CMAKE_EXE_LINKER_FLAGS  "${CMAKE_EXE_LINKER_FLAGS} ${COVERAGE_FLAGS}" )
 endif()
 
+# export WITH_GO=yes to build the go bindings and test binary
+if(DEFINED ENV{WITH_GO})
+  message(STATUS "WITH_GO detected in main CMakeLists.txt to build go bindings")
+  include(GolangSimple)
+endif()
+
 include_directories(.)
 add_subdirectory( etc )
 add_subdirectory( src )

README.md

@@ -104,13 +104,37 @@ be set to the same prefix as was used to install the target flux-core.
 
 For example, if flux-core was installed in `$FLUX_CORE_PREFIX`:
 
-```
+```bash
 ./configure --prefix=${FLUX_CORE_PREFIX}
 make
 make check
 make install
 ```
 
+To build go bindings, you will need go (tested with 1.19.10) available, and then:
+
+```bash
+export WITH_GO=yes
+./configure
+make
+```
+
+To run just one test, you can cd into t
+
+```bash
+$ ./t9001-golang-basic.t 
+ok 1 - match allocate 1 slot: 1 socket: 1 core (pol=default)
+ok 2 - match allocate 2 slots: 2 sockets: 5 cores 1 gpu 6 memory
+# passed all 2 test(s)
+1..2
+```
+
+To run full tests (more robust and mimics what happens in CI) you can do:
+
+```bash
+make check
+```
+
 ##### Flux Instance
 
 The examples below walk through exercising functioning flux-sched modules (i.e.,

cmake/GolangSimple.cmake

@@ -0,0 +1,31 @@
+
+set(CUSTOM_GO_PATH "${CMAKE_SOURCE_DIR}/resource/reapi/bindings/go")
+set(GOPATH "${CMAKE_CURRENT_BINARY_DIR}/go")
+
+# This probably isn't necessary, although if we could build fluxcli into it maybe
+file(MAKE_DIRECTORY ${GOPATH})
+
+# ADD_GO_INSTALLABLE_PROGRAM builds a custom go program (primarily for testing)
+function(BUILD_GO_PROGRAM NAME MAIN_SRC CGO_CFLAGS CGO_LIBRARY_FLAGS)
+  message(STATUS "GOPATH: ${GOPATH}")
+  message(STATUS "CGO_LDFLAGS: ${CGO_LIBRARY_FLAGS}")
+  get_filename_component(MAIN_SRC_ABS ${MAIN_SRC} ABSOLUTE)
+  add_custom_target(${NAME})
+
+  # IMPORTANT: the trick to getting *spaces* to render in COMMAND is to convert them to ";"
+  # string(REPLACE <match-string> <replace-string> <out-var> <input>...)
+  STRING(REPLACE " " ";" CGO_LIBRARY_FLAGS ${CGO_LIBRARY_FLAGS})  
+  add_custom_command(TARGET ${NAME}
+                    COMMAND GOPATH=${GOPATH}:${CUSTOM_GO_PATH} GOOS=linux G0111MODULE=off CGO_CFLAGS="${CGO_CFLAGS}" CGO_LDFLAGS='${CGO_LIBRARY_FLAGS}' go build -ldflags '-w'
+                    -o "${CMAKE_CURRENT_SOURCE_DIR}/${NAME}"
+                    ${CMAKE_GO_FLAGS} ${MAIN_SRC}
+                    WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+                    DEPENDS ${MAIN_SRC_ABS}
+                    COMMENT "Building Go library")
+  foreach(DEP ${ARGN})
+    add_dependencies(${NAME} ${DEP})
+  endforeach()
+
+  add_custom_target(${NAME}_all ALL DEPENDS ${NAME})
+  install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/${NAME} DESTINATION bin)
+endfunction(BUILD_GO_PROGRAM)

resource/reapi/bindings/CMakeLists.txt

@@ -18,3 +18,8 @@ add_library ( reapi_module STATIC
 target_link_libraries(reapi_module PRIVATE
     flux::core
     )
+
+if(DEFINED ENV{WITH_GO})
+    message(STATUS "WITH_GO is set to build go bindings")
+    add_subdirectory( go )
+endif()

resource/reapi/bindings/go/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory( src )

resource/reapi/bindings/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/flux-framework/flux-sched/resource/reapi/bindings/go
+
+go 1.19

resource/reapi/bindings/go/src/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory( test )