Confine to the crate project structure (#1)

* defining project structure

* removed wrapper.cpp config from build.rs

* added tests for init + added bindings for fn from hpx/init.hpp as per public api.

* added License

* removed main.rs and added lib.rs lib.rs will also contains docs for the crate

* updated README.md

* corrected docs to pass the doc test

* removed unnecessary comments

* removed linking to hpx_iostreams and hpx dylib

---------

Signed-off-by: Dikshant <[email protected]>

.gitignore

@@ -0,0 +1,4 @@
+/target
+/Cargo.lock
+hpx-sys/target/
+.*.sw*

Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "hpx-rs"
+version = "0.1.0"
+authors = ["Shreyas Atre <[email protected]>", "Dikshant <[email protected]"]
+edition = "2021"
+readme = "README.md"
+repository = "https://github.com/STEllAR-GROUP/hpx-rs"
+description = """
+Bindings to hpx for interoperating with stellar-group hpx library for 
+concurrency and parallelism.
+"""
+categories = ["api-bindings"]
+license = "BSL-1.0"
+publish = false
+
+[dependencies]
+hpx-sys = { path = "hpx-sys", version = "0.1.0" }
+
+[workspace]
+members = []

LICENSE

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

README.md

@@ -1 +1,11 @@
-# hpx-rs
+# hpx-rs
+Rust bindings to HPX, C++ Standard Library for Concurrency and
+Parallelism.
+
+## Rust version requirements
+hpx-rs works with stable Rust.
+
+## Version of hpx
+Currently this library requires hpx-1.10(or newer). The user is required
+to pre-install hpx and set the pkg-config to point to "*.pc" files of
+hpx. The hpx-sys crate will then link to the hpx.

hpx-sys/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "hpx-sys"
+authors = ["Dikshant <[email protected]>", "Shreyas Atre <[email protected]>"]
+version = "0.1.0"
+edition = "2021"
+build = "build.rs"
+description = "Native bindings to the hpx library"
+license = "BSL-1.0"
+
+[lib]
+name = "hpx_sys"
+path = "src/lib.rs"
+
+[dependencies]
+cxx = "1.0"
+serial_test = "*"
+
+[build-dependencies]
+cxx-build = "1.0"
+pkg-config = "0.3.30"
+
+[dev-dependencies]
+serial_test = "*"

hpx-sys/build.rs

@@ -0,0 +1,68 @@
+#![allow(unused_imports, dead_code)]
+use std::{
+    env,
+    path::{Path, PathBuf},
+};
+
+/// Try to use user installed hpx and emit necessary build script instructions.
+fn try_hpx_application() -> Result<pkg_config::Library, pkg_config::Error> {
+    let mut cfg = pkg_config::Config::new();
+    match cfg
+        .range_version("1.10.0".."1.12.0")
+        .probe("hpx_application")
+    {
+        Ok(lib) => {
+            for include in &lib.include_paths {
+                println!("cargo:root={}", include.display());
+            }
+            Ok(lib)
+        }
+        Err(e) => {
+            println!("cargo:warning=failed to probe hpx_application: {e}");
+            Err(e)
+        }
+    }
+}
+
+fn try_hpx_component() -> Result<pkg_config::Library, pkg_config::Error> {
+    let mut cfg = pkg_config::Config::new();
+    match cfg.range_version("1.10.0".."1.12.0").probe("hpx_component") {
+        Ok(lib) => {
+            for include in &lib.include_paths {
+                println!("cargo:root={}", include.display());
+            }
+            Ok(lib)
+        }
+        Err(e) => {
+            println!("cargo:warning=failed to probe hpx_component: {e}");
+            Err(e)
+        }
+    }
+}
+
+/// User is required to specify linker files path for hpx
+/// because by default Cargo will export `DYLD_LIBRARY_PATH=/opt/local/lib:...`
+/// `export DYLD_LIBRARY_PATH=~/stllr/hpx-install/lib:$DYLD_LIBRARY_PATH` and `export
+/// LD_LIBRARY_PATH on linux`
+fn main() {
+    let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
+    let lib_rs_path = Path::new(&manifest_dir).join("src").join("lib.rs");
+    println!(
+        "cargo:warning=Looking for lib.rs at: {}",
+        lib_rs_path.display()
+    );
+    let mut build = cxx_build::bridge(lib_rs_path);
+    let hpx_application = match try_hpx_application() {
+        Ok(lib) => lib,
+        Err(_) => panic!("Failed to find hpx_application using pkg-config"),
+    };
+
+    for path in &hpx_application.include_paths {
+        build.include(path);
+    }
+
+    build.std("c++17").compile("hpx-sys");
+
+    println!("cargo:rerun-if-changed=src/lib.rs");
+    println!("cargo:rerun-if-changed=include/wrapper.h");
+}

hpx-sys/include/wrapper.h

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <hpx/hpx_init.hpp>
+#include <iostream>
+#include <cstdint>
+#include <vector>
+
+#include "rust/cxx.h"
+
+
+/*inline std::int32_t start() { return hpx::start(nullptr, 0, nullptr); }*/
+
+/*inline std::int32_t start(rust::Fn<int(int, char **)> rust_fn, int argc, char **argv) {*/
+/*	return hpx::start(*/
+/*		[&](int argc, char **argv) {*/
+/*		return rust_fn(argc, argv);*/
+/*        },*/
+/*        argc, argv);*/
+/*}*/
+
+inline std::int32_t init(rust::Fn<int(int, char **)> rust_fn, int argc, char **argv) {
+	return hpx::init(
+		[&](int argc, char **argv) {
+		return rust_fn(argc, argv);
+        },
+        argc, argv);
+}
+
+inline std::int32_t finalize_with_timeout(double shutdown_timeout, double localwait) {
+	return hpx::finalize(shutdown_timeout, localwait);
+}
+
+inline void terminate() {
+	return hpx::terminate();
+}
+
+inline std::int32_t disconnect() {
+	return hpx::disconnect();
+}
+
+inline std::int32_t disconnect_with_timeout(double shutdown_timeout, double localwait) {
+	return hpx::disconnect(shutdown_timeout, localwait);
+}
+
+inline std::int32_t finalize() { return hpx::finalize(); }
+
+/*inline std::int32_t stop() { return hpx::stop(); }*/

hpx-sys/src/lib.rs

@@ -0,0 +1,60 @@
+#![doc(html_root_url = "https://github.com/STEllAR-GROUP/hpx-rs")]
+#![allow(bad_style, non_camel_case_types, unused_extern_crates)]
+#![allow(dead_code, unused_imports)]
+
+#[cxx::bridge]
+pub mod ffi {
+    unsafe extern "C++" {
+        include!("hpx-sys/include/wrapper.h");
+
+        //fn start() -> i32;
+        unsafe fn init(
+            func: unsafe fn(i32, *mut *mut c_char) -> i32,
+            argc: i32,
+            argv: *mut *mut c_char,
+        ) -> i32;
+
+        fn finalize() -> i32;
+        fn finalize_with_timeout(shutdown_timeout: f64, localwait: f64) -> i32;
+        fn terminate();
+        fn disconnect() -> i32;
+        fn disconnect_with_timeout(shutdown_timeout: f64, localwait: f64) -> i32;
+        //fn stop() -> i32;
+    }
+}
+
+// ================================================================================================
+// Tests (to be shifted to systests crate within hpx-rs workspace)
+// ================================================================================================
+#[cfg(test)]
+mod tests {
+    use super::ffi;
+    use serial_test::serial;
+    use std::ffi::CString;
+    use std::os::raw::c_char;
+    use std::thread;
+    use std::time::Duration;
+
+    fn create_c_args(args: &[&str]) -> (i32, Vec<*mut c_char>) {
+        let c_args: Vec<CString> = args.iter().map(|s| CString::new(*s).unwrap()).collect();
+        let ptrs: Vec<*mut c_char> = c_args.iter().map(|s| s.as_ptr() as *mut c_char).collect();
+        (ptrs.len() as i32, ptrs)
+    }
+
+    #[test]
+    fn test_init_finalize() {
+        let (argc, mut argv) = create_c_args(&["testing", "arg1", "arg2"]);
+
+        let dummy_main = |_argc: i32, _argv: *mut *mut c_char| -> i32 {
+            println!("Dummy fn called");
+            // to exit hpx::init you are required to shutdown hpx runtime
+            ffi::finalize();
+            0
+        };
+
+        unsafe {
+            let result = ffi::init(dummy_main, argc, argv.as_mut_ptr());
+            assert_eq!(result, 0);
+        }
+    }
+}

src/lib.rs

@@ -0,0 +1,14 @@
+//!
+//! # HPX bindings for Rust
+//! This library contains bindings to [HPX][1], C++ Standard Library for Concurrency and
+//! Parallellism. This Library is a work in progress and lacks several bindings, So be warned!
+//! It will build the library and link it to HPX. To use this library you need to set
+//! PKG_config_PATH to point to hpx "*.pc" files by executing the following in terminal:
+//! ```sh
+//! export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HPX_LOCATION/lib/pkgconfig
+//! ```
+//! If on mac you also need to set DYLD path using the following:
+//! ```sh
+//! export DYLD_LIBRARY_PATH=$HPX_LOCATION/lib:$DYLD_LIBRARY_PATH
+//! ```
+//! [1]: https://hpx.stellar-group.org/