flakoboros 0.1.0__tar.gz

flakoboros-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: flakoboros
+Version: 0.1.0
+Summary: Circular Packaging framework with nix Flakes, including ROS support
+Author: Guilhem Saurel
+Author-email: Guilhem Saurel <guilhem.saurel@laas.fr>
+Requires-Dist: catkin-pkg>=1.1.0
+Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: xdg-base-dirs>=6.0.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# flakoboros
+
+<img src="./docs/logo.svg" alt="flakoboros logo: the 6 lambda from nix flake, but rotated as if they are eating each other as a ouroboros">
+
+Circular Packaging framework with nix Flakes, including ROS support
+
+# Goal
+
+When one package is defined in a flake, we can by default:
+
+- `nix build`: build the package (and run its tests)
+- `nix shell`: open a shell with the package ready to be used
+- `nix develop`: open a shell without the built package, but with everything required to build it
+- `nix run`: execute the main program from the package
+
+Flakoboros provide the same experience with multiple packages in a flake:
+
+- `nix build`: build all packages (and run their tests)
+- `nix shell`: open a shell with all packages ready to be used
+- `nix develop`: open a shell without any of the packages, but with everything required to build them all
+- `nix run`: execute the main program from all the packages (eg. a python interpreter with all the python modules available)
+
+To do so, the main API is designed around the idea that your packages are distributed in another more-or-less central Nix repository (eg. nixpkgs or nix-ros-overlay),
+and you just need `my-package.overrideAttrs { src = lib.cleanSource ./. }` in the flake of the source.
+
+## Circular Packaging ?
+
+That notion of re-using an existing distribution of a package inside its source.
+
+<!-- More details in [rationale.md](./docs/rationale.md) -->
+
+## API overview
+
+example for [eigenpy](https://github.com/stack-of-tasks/eigenpy):
+
+```nix
+{
+  description = "Bindings between Numpy and Eigen using Boost.Python";
+
+  inputs.flakoboros.url = "github:gepetto/flakoboros";
+
+  outputs =
+    inputs:
+    inputs.flakoboros.lib.mkFlakoboros inputs (
+      { lib, ... }:
+      {
+        pyOverrideAttrs.eigenpy = {
+          src = lib.cleanSource ./.;
+        };
+      }
+    );
+}
+```
+
+<details>
+<summary>If you need access to more data, a callable form is also available (clic here to reveal)</summary>
+
+```nix
+{
+  pyOverrideAttrs.example-robot-data =
+    { pkgs-final, pkgs-prev, drv-final, drv-prev, py-final, py-prev, ... }:
+    {
+      src = lib.cleanSource ./.;
+      cmakeFlags = [ (lib.cmakeBool "BUILD_TESTING" drv-final.doCheck) ];
+      nativeBuildInputs = drv-prev.nativeBuildinputs ++ [ pkgs-final.ninja ];
+      dependencies = drv-prev.dependencies ++ [ py-final.rerun-sdk ];
+    };
+}
+```
+</details>
+
+<details>
+<summary>Behind the scene, this is a shallow wrapper around `flake-parts.lib.mkFlake`, which can be used directly (clic here to reveal)</summary>
+
+```nix
+{
+  description = "Bindings between Numpy and Eigen using Boost.Python";
+
+  inputs = {
+    flakoboros.url = "github:gepetto/flakoboros";
+    flake-parts.follows = "flakoboros/flake-parts";
+    systems.follows = "flakoboros/systems";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } (
+      { lib, ... }:
+      {
+        systems = import inputs.systems;
+        imports = [
+          inputs.flakoboros.flakeModule
+          {
+            flakoboros = {
+              pyOverrideAttrs.eigenpy = {
+                src = lib.cleanSource ./.;
+              };
+            };
+          }
+        ];
+      }
+    );
+}
+```
+</details>
+
+<!-- (the full list is defined in [options.nix](./options.nix)) -->
+
+This will:
+
+- define `overlays.flakoboros` with this override
+- (if you don't opt-out) instanciate `pkgs` with that overlay
+- inherit this in `packages.${system}.py-eigenpy`
+- define `packages.${system}.default` as a `buildEnv` including all others `packages.${system}.*`  (for `nix build` & `nix shell`)
+- define `devShells.${system}.default` as a `mkShell` with `inputsFrom` the same `packages.${system}.*` (for `nix develop` / `nix-direnv`)
+
+## ROS
+
+If you have ROS packages, the `default` package and devShell will use a default ROS distribution (eg. `rolling`), but the same features are available for other distros, with eg.
+
+- `nix build .#ros-humble`
+- `nix shell .#ros-jazzy`
+- `nix develop .#ros-kilted`
+- `nix run .#ros-rolling`
+
+Also, standard ROS tools like colcon and ros2cli will be included.
+
+## Extend `pkgs`, aka alternate universes
+
+```nix
+{
+  extends.eigen5 = final: { eigen = final.eigen_5; };
+  pyOverrideAttrs.eigenpy = {
+    src = lib.cleanSource ./.;
+  };
+};
+```
+
+This will:
+
+- define `pkgs`, `packages.${system}.py-eigenpy` and `packages.${system}.default` as before
+- define `pkgs.pkgs-eigen5` as another `pkgs` instance but where `eigen` is overriden everywhere by `eigen_5`
+- define `packages.${system}.pkgs-eigen5`, equivalent to `packages.${system}.default` but with eigen 5
+- add scoped everything else, eg. `packages.${system}.pkgs-eigen5.py-eigenpy` (technically `packages.${system}.pkgs-eigen5.passthru.py-eigenpy`)
+- define `devShells.${system}.pkgs-eigen5`
+
+So in your CI, you can build `.` and `.#pkgs-eigen5` to check all your stack with both eigen 3.4.1 and 5.0.1.
+
+Also, you can either `echo 'use flake .' > .envrc` or `echo 'use flake .#pkgs-eigen5' > .envrc`, and follow your usual `cmake -B build && cmake --build build` workflow.

flakoboros-0.1.0/README.md

@@ -0,0 +1,149 @@
+# flakoboros
+
+<img src="./docs/logo.svg" alt="flakoboros logo: the 6 lambda from nix flake, but rotated as if they are eating each other as a ouroboros">
+
+Circular Packaging framework with nix Flakes, including ROS support
+
+# Goal
+
+When one package is defined in a flake, we can by default:
+
+- `nix build`: build the package (and run its tests)
+- `nix shell`: open a shell with the package ready to be used
+- `nix develop`: open a shell without the built package, but with everything required to build it
+- `nix run`: execute the main program from the package
+
+Flakoboros provide the same experience with multiple packages in a flake:
+
+- `nix build`: build all packages (and run their tests)
+- `nix shell`: open a shell with all packages ready to be used
+- `nix develop`: open a shell without any of the packages, but with everything required to build them all
+- `nix run`: execute the main program from all the packages (eg. a python interpreter with all the python modules available)
+
+To do so, the main API is designed around the idea that your packages are distributed in another more-or-less central Nix repository (eg. nixpkgs or nix-ros-overlay),
+and you just need `my-package.overrideAttrs { src = lib.cleanSource ./. }` in the flake of the source.
+
+## Circular Packaging ?
+
+That notion of re-using an existing distribution of a package inside its source.
+
+<!-- More details in [rationale.md](./docs/rationale.md) -->
+
+## API overview
+
+example for [eigenpy](https://github.com/stack-of-tasks/eigenpy):
+
+```nix
+{
+  description = "Bindings between Numpy and Eigen using Boost.Python";
+
+  inputs.flakoboros.url = "github:gepetto/flakoboros";
+
+  outputs =
+    inputs:
+    inputs.flakoboros.lib.mkFlakoboros inputs (
+      { lib, ... }:
+      {
+        pyOverrideAttrs.eigenpy = {
+          src = lib.cleanSource ./.;
+        };
+      }
+    );
+}
+```
+
+<details>
+<summary>If you need access to more data, a callable form is also available (clic here to reveal)</summary>
+
+```nix
+{
+  pyOverrideAttrs.example-robot-data =
+    { pkgs-final, pkgs-prev, drv-final, drv-prev, py-final, py-prev, ... }:
+    {
+      src = lib.cleanSource ./.;
+      cmakeFlags = [ (lib.cmakeBool "BUILD_TESTING" drv-final.doCheck) ];
+      nativeBuildInputs = drv-prev.nativeBuildinputs ++ [ pkgs-final.ninja ];
+      dependencies = drv-prev.dependencies ++ [ py-final.rerun-sdk ];
+    };
+}
+```
+</details>
+
+<details>
+<summary>Behind the scene, this is a shallow wrapper around `flake-parts.lib.mkFlake`, which can be used directly (clic here to reveal)</summary>
+
+```nix
+{
+  description = "Bindings between Numpy and Eigen using Boost.Python";
+
+  inputs = {
+    flakoboros.url = "github:gepetto/flakoboros";
+    flake-parts.follows = "flakoboros/flake-parts";
+    systems.follows = "flakoboros/systems";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } (
+      { lib, ... }:
+      {
+        systems = import inputs.systems;
+        imports = [
+          inputs.flakoboros.flakeModule
+          {
+            flakoboros = {
+              pyOverrideAttrs.eigenpy = {
+                src = lib.cleanSource ./.;
+              };
+            };
+          }
+        ];
+      }
+    );
+}
+```
+</details>
+
+<!-- (the full list is defined in [options.nix](./options.nix)) -->
+
+This will:
+
+- define `overlays.flakoboros` with this override
+- (if you don't opt-out) instanciate `pkgs` with that overlay
+- inherit this in `packages.${system}.py-eigenpy`
+- define `packages.${system}.default` as a `buildEnv` including all others `packages.${system}.*`  (for `nix build` & `nix shell`)
+- define `devShells.${system}.default` as a `mkShell` with `inputsFrom` the same `packages.${system}.*` (for `nix develop` / `nix-direnv`)
+
+## ROS
+
+If you have ROS packages, the `default` package and devShell will use a default ROS distribution (eg. `rolling`), but the same features are available for other distros, with eg.
+
+- `nix build .#ros-humble`
+- `nix shell .#ros-jazzy`
+- `nix develop .#ros-kilted`
+- `nix run .#ros-rolling`
+
+Also, standard ROS tools like colcon and ros2cli will be included.
+
+## Extend `pkgs`, aka alternate universes
+
+```nix
+{
+  extends.eigen5 = final: { eigen = final.eigen_5; };
+  pyOverrideAttrs.eigenpy = {
+    src = lib.cleanSource ./.;
+  };
+};
+```
+
+This will:
+
+- define `pkgs`, `packages.${system}.py-eigenpy` and `packages.${system}.default` as before
+- define `pkgs.pkgs-eigen5` as another `pkgs` instance but where `eigen` is overriden everywhere by `eigen_5`
+- define `packages.${system}.pkgs-eigen5`, equivalent to `packages.${system}.default` but with eigen 5
+- add scoped everything else, eg. `packages.${system}.pkgs-eigen5.py-eigenpy` (technically `packages.${system}.pkgs-eigen5.passthru.py-eigenpy`)
+- define `devShells.${system}.pkgs-eigen5`
+
+So in your CI, you can build `.` and `.#pkgs-eigen5` to check all your stack with both eigen 3.4.1 and 5.0.1.
+
+Also, you can either `echo 'use flake .' > .envrc` or `echo 'use flake .#pkgs-eigen5' > .envrc`, and follow your usual `cmake -B build && cmake --build build` workflow.

flakoboros-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "flakoboros"
+version = "0.1.0"
+description = "Circular Packaging framework with nix Flakes, including ROS support"
+readme = "README.md"
+authors = [
+    { name = "Guilhem Saurel", email = "guilhem.saurel@laas.fr" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "catkin-pkg>=1.1.0",
+    "httpx[http2]>=0.28.1",
+    "xdg-base-dirs>=6.0.2",
+]
+
+[project.scripts]
+flakoboros = "flakoboros:main"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipython>=9.14.1",
+]

flakoboros-0.1.0/src/flakoboros/__init__.py

@@ -0,0 +1,147 @@
+"""
+Sync https://github.com/ros/rosdistro/tree/master/rosdep in $XDG_CACHE_HOME/flakoboros
+
+This will download 3 small files once a month.
+Hopefully we won't need GITHUB_TOKEN.
+For this let's at least respect some user agent etiquette.
+"""
+
+import argparse
+import json
+import logging
+import pathlib
+import subprocess
+import time
+
+from catkin_pkg.package import parse_package
+import httpx
+from xdg_base_dirs import xdg_cache_home
+
+
+NAME = "flakoboros"
+LOGGER = logging.getLogger(NAME)
+JSON = f"{NAME}.json"
+PACKAGE = "package.xml"
+CACHE = xdg_cache_home() / JSON
+
+FLAKE_TEMPLATE = """
+{
+  inputs.gazebros2nix.url = "github:gepetto/gazebros2nix";
+
+  outputs =
+    inputs:
+    inputs.gazebros2nix.lib.mkFlakoboros inputs (
+      { lib, ... }: lib.importJSON ./wsconf.json
+    );
+}
+"""
+
+parser = argparse.ArgumentParser()
+parser.add_argument("-r", "--ros", default="rolling")
+parser.add_argument(
+    "-d",
+    "--dist",
+    default="https://gepetto.github.io/gazebros2nix",
+    help="source for the flakoboros.json file",
+)
+
+
+def get_cache(dist):
+    CACHE.parent.mkdir(exist_ok=True)
+
+    if not (CACHE.exists() and (time.time() - CACHE.stat().st_mtime) < 24 * 3600):
+        r = httpx.get(f"{dist}/{JSON}")
+        r.raise_for_status()
+        CACHE.write_text(r.text)
+
+    return json.loads(CACHE.read_text())
+
+
+def ensure_setup():
+    flake = pathlib.Path("flake.nix")
+    if not flake.is_file():
+        flake.write_text(FLAKE_TEMPLATE)
+
+    envrc = pathlib.Path(".envrc")
+    if not envrc.is_file():
+        envrc.write_text("use flake .")
+        try:
+            subprocess.run(
+                ["direnv", "allow"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except FileNotFoundError:
+            LOGGER.warning(
+                "direnv is not available, you will need to manually run 'nix develop'"
+            )
+
+
+def main():
+    args = parser.parse_args()
+
+    src = pathlib.Path("src")
+    if not src.is_dir():
+        LOGGER.error("There is no 'src/' directory here")
+        return
+
+    ensure_setup()
+
+    cache = get_cache(args.dist)
+
+    wsconf = {
+        "extraPackages": set(),
+        "extraPyPackages": set(),
+        "extraRosPackages": set(),
+        "extraDevPackage": set(),
+        "extraDevPyPackages": set(),
+        "extraDevRosPackages": set(),
+    }
+    for root, _dirs, files in src.walk():
+        if PACKAGE in files:
+            pkg = parse_package(root)
+            name = pkg.name.replace("_", "-")
+            if name in cache["ros"]:
+                wsconf["extraDevRosPackages"].add(name)
+                LOGGER.info("added %s", pkg.name)
+            else:
+                LOGGER.warning(
+                    "%s is not available in the distribution. It would be better to add it.",
+                    pkg.name,
+                )
+                for dep in (
+                    pkg.buildtool_depends
+                    + pkg.buildtool_export_depends
+                    + pkg.doc_depends
+                    + pkg.build_depends
+                    + pkg.exec_depends
+                    + pkg.build_export_depends
+                    + pkg.test_depends
+                ):
+                    name = dep.name.replace("_", "-")
+                    if dep in cache["ros"]:
+                        wsconf["extraRosPackages"].add(name)
+                    elif dep in cache["rosdep"]:
+                        for rosdep in cache["rosdep"][name]:
+                            if rosdep.startswith("python3Packages."):
+                                wsconf["extraPyPackages"].add(
+                                    rosdep.removePrefix("python3Packages.")
+                                )
+                            else:
+                                wsconf["extraPackages"].add(rosdep)
+                    elif dep in cache["python"]:
+                        wsconf["extraPyPackages"].add(name)
+                    elif dep in cache["pkgs"]:
+                        wsconf["extraPackages"].add(name)
+                    else:
+                        LOGGER.error(
+                            "%s is unknown. maybe you should clone it too ?", name
+                        )
+
+    wsconf = {k: list(v) for k, v in wsconf.items() if v}
+    wsconf["rosShellDistro"] = args.ros
+    pathlib.Path("wsconf.json").write_text(json.dumps(wsconf))
+
+
+if __name__ == "__main__":
+    main()