Merge remote-tracking branch 'origin/master' into fix-unsound

# Conflicts:
#	src/lib.rs
#	src/option.rs

.github/workflows/ci.yml

@@ -10,75 +10,33 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  check:
-    name: Check
-    runs-on: ubuntu-22.04
-    strategy:
-      matrix:
-        rust:
-          - stable
-          - 1.60.0
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: ${{ matrix.rust }}
-          override: true
-      - run: sudo apt-get -y install libmetis-dev libclang-dev
-      - uses: actions-rs/cargo@v1
-        with:
-          command: check
-
   test:
     name: Test Suite
     runs-on: ubuntu-22.04
     strategy:
       matrix:
         rust:
           - stable
-          - 1.60.0
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: ${{ matrix.rust }}
-          override: true
-      - run: sudo apt-get -y install libmetis-dev libclang-dev
-      - uses: actions-rs/cargo@v1
-        with:
-          command: test
-
-  fmt:
-    name: Rustfmt
-    runs-on: ubuntu-22.04
+          - 1.67.0
+          - nightly
+        features:
+          - vendored
+          - use-system
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
+      - uses: actions/checkout@v4
         with:
-          profile: minimal
-          toolchain: stable
-          override: true
-          components: rustfmt
-      - uses: actions-rs/cargo@v1
+          submodules: recursive
+      - uses: dtolnay/rust-toolchain@master
         with:
-          command: fmt
-          args: -p metis -- --check
-
-  clippy:
-    name: Clippy
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-          components: clippy
+          components: clippy, rustfmt
+          toolchain: ${{ matrix.rust }}
       - run: sudo apt-get -y install libmetis-dev libclang-dev
-      - uses: actions-rs/cargo@v1
-        with:
-          command: clippy
-          args: -p metis -- -D warnings
+        if: matrix.features == 'use-system'
+      - name: Check Format
+        run: cargo fmt -- --check
+      - name: Run Check
+        run: cargo check --features ${{ matrix.features }} --no-default-features
+      - name: Run Clippy
+        run: cargo clippy --features ${{ matrix.features }} --no-default-features
+      - name: Run Tests
+        run: cargo test --features ${{ matrix.features }} --no-default-features --all

.github/workflows/rustdoc.yml

@@ -16,20 +16,21 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
       - uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           profile: minimal
           override: true
           components: rustfmt, rust-src
-      - run: sudo apt-get -y install libmetis-dev libclang-dev
       - uses: actions-rs/cargo@v1
         with:
           command: doc
           args: --all --no-deps
       - name: Deploy Docs
-        uses: peaceiris/actions-gh-pages@364c31d33bb99327c77b3a5438a83a357a6729ad # v3.4.0
+        uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: gh-pages

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "vendor/GKlib"]
+	path = vendor/GKlib
+	url = https://github.com/KarypisLab/GKlib
+[submodule "vendor/metis"]
+	path = vendor/metis
+	url = https://github.com/KarypisLab/METIS

Cargo.toml

@@ -3,8 +3,8 @@ members = [".", "metis-sys"]
 
 [package]
 name = "metis"
-version = "0.1.2"
-authors = ["Hubert Hirtz <[email protected]>"]
+version = "0.2.0"
+authors = ["Hubert Hirtz <[email protected]>", "Cedric Chevalier <[email protected]>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/LIHPC-Computational-Geometry/metis-rs"
@@ -14,5 +14,14 @@ keywords = ["graph", "mesh", "matrix", "partitioning", "ordering"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+default = ["metis-sys/default"]
+
+# Build and statically link to METIS and GKLib.
+vendored = ["metis-sys/vendored"]
+
+# Use existing METIS install and links dynamically to it.
+use-system = ["metis-sys/use-system"]
+
 [dependencies]
-metis-sys = { version = "0.2", path = "metis-sys" }
+metis-sys = { version = "0.3", path = "metis-sys", default-features = false }

README.md

@@ -1,41 +1,48 @@
 # metis-rs
 
-Idiomatic bindings to [libmetis][METIS], a graph and mesh partitioner.
+**metis-rs** is a Rust library providing idiomatic bindings to [libmetis][METIS], a library for graph and mesh
+partitioning. It is made to be used with Rust version 1.67.0 or above.
 
-## Building
+## Features
 
-Prerequisites:
+### Use of Vendored Feature
 
-- METIS
-- clang v5.0 or above
-- Rust v1.60.0 or above
+The `vendored` feature enables metis-rs to build METIS from source and link to it statically. If not enabled, metis-rs
+looks for an existing installation and links to it dynamically.
 
-Bindings to METIS are made on the fly.  If METIS is installed in a non-standard
-location, please use the following commands:
+### Use of System-wide Feature
 
-    export METISDIR=path/to/your/metis/installation
-    export CPATH="$METISDIR/include"
-    export RUSTFLAGS="-L$METISDIR/lib"
+The `use-system` feature enables metis-rs to use the system-wide installation of METIS. If not enabled, metis-rs will
+refer to its own version of METIS.
 
-The environment variable `$METISDIR` must point to a directory containing a
-`lib/` and a `include/` directory containing the shared libraries and the
-headers of METIS, respectively.
+Please note, `vendored` and `use-system` features are mutually exclusive.
 
-Once these variables are set, you can build the bindings with `cargo build`.
+## Guidance for non-standard METIS installations
 
-### Build the documentation
+If you enabled the `use-system` feature and METIS is installed in a non-standard location, you must set the following
+environment variables:
+```bash
+export METISDIR=path/to/your/metis/installation
+export CPATH="$METISDIR/include"
+export RUSTFLAGS="-L$METISDIR/lib"
+```
 
-If your METIS installation lies in a non-standard path, you will need to set
-the `RUSTDOCFLAGS` environment variable to build the documentation:
+`$METISDIR` must point to a directory containing both `lib/` and `include/` directories with METIS's shared libraries and headers, respectively.
 
-    export RUSTDOCFLAGS="-L$METISDIR/lib"
+## Building the documentation
 
-Then you can call `cargo doc --no-deps --open`.
+To build the documentation, especially if METIS is installed in a non-standard location, set the `RUSTDOCFLAGS` environment variable:
+
+```bash
+export RUSTDOCFLAGS="-L$METISDIR/lib"
+```
+Then the following command will generate and open the documentation:
+```bash
+cargo doc --no-deps --open
+```
 
 ## License
 
-This program is distributed under the terms of both the MIT license and the
-Apache License (Version 2.0).  See `LICENSE-APACHE` and `LICENSE-MIT` for
-details.
+metis-rs is distributed under the terms of both the MIT license and the Apache License (Version 2.0). Refer to `LICENSE-APACHE` and `LICENSE-MIT` for more details.
 
-[METIS]: http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
+[METIS]: http://glaros.dtc.umn.edu/gkhome/metis/metis/overview

examples/graph.rs

@@ -1,9 +1,9 @@
 use metis::Graph;
 
 fn main() -> Result<(), metis::Error> {
-    let xadj = &mut [0, 2, 5, 8, 11, 13, 16, 20, 24, 28, 31, 33, 36, 39, 42, 44];
+    let xadj = &[0, 2, 5, 8, 11, 13, 16, 20, 24, 28, 31, 33, 36, 39, 42, 44];
     #[rustfmt::skip]
-    let adjncy = &mut [
+    let adjncy = &[
         1, 5,
         0, 2, 6,
         1, 3, 7,

metis-sys/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "metis-sys"
-version = "0.2.1"
-authors = ["Hubert Hirtz <[email protected]>"]
+version = "0.3.0"
+authors = ["Hubert Hirtz <[email protected]>", "Cedric Chevalier <[email protected]>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/LIHPC-Computational-Geometry/metis-rs"
@@ -11,5 +11,19 @@ categories = ["external-ffi-bindings", "mathematics"]
 keywords = ["graph", "mesh", "matrix", "partitioning", "ordering"]
 
 
+[features]
+default = ["vendored"]
+
+# Build and statically link to METIS and GKLib.
+vendored = ["dep:cc"]
+
+# Use existing METIS install and links dynamically to it.
+use-system = ["bindgen"]
+
+# Regenerate bindings in metis-sys/gen/bindings.rs from METIS in the "vendor"
+# directory. Also enables "vendored".
+generate-bindings = ["vendored", "bindgen"]
+
 [build-dependencies]
-bindgen = { version = "0.66", default-features = false, features = ["runtime"] }
+bindgen = { version = "0.69", default-features = false, features = ["runtime"], optional = true }
+cc = { version = "1", features = ["parallel"], optional = true }