make sboxU an installable python package via pip and nix

.gitignore

@@ -1,13 +1,14 @@
+# ignore build output
+build/
 # ignore compiled files
 *.pyc
 *.so
-sboxU/sboxU_cython/cpp_ccz.cpp
-sboxU/sboxU_cython/cpp_diff_lin.cpp
-sboxU/sboxU_cython/cpp_equiv.cpp
-sboxU/sboxU_cython/cpp_fp.cpp
-sboxU/sboxU_cython/cpp_utils.cpp
-sboxU/sboxU_cython/cpp_diff_lin_no_fp_lat.cpp
-sboxU/sboxU_cython/build/
+/sboxU/sboxU_cython/cpp_ccz.cpp
+/sboxU/sboxU_cython/cpp_diff_lin.cpp
+/sboxU/sboxU_cython/cpp_equiv.cpp
+/sboxU/sboxU_cython/cpp_fp.cpp
+/sboxU/sboxU_cython/cpp_utils.cpp
+/sboxU/sboxU_cython/cpp_diff_lin_no_fp_lat.cpp
+/sboxU/sboxU_cython/cpp_equiv_approx.cpp
 # ignore automatically generated files
 *~
-

README.md

@@ -24,40 +24,38 @@ or, on macOS:
     brew install libomp
 
 
-## Usage
+## Install
 
-To retrieve this module, use the following command:
+### Direct Installation via SAGE
 
-    git clone https://github.com/lpp-crypto/sboxU/
+To use this module, use the following command:
 
-Then, you need to compile the content of the `sboxU/sboxU_cython` folder.
-This process only relies on SAGE To compile it:
+    sage --pip install git+https://github.com/lpp-crypto/sboxU
 
-    cd sboxU/sboxU_cython
-    sage setup.py build_ext --inplace
+This compiles the C++ part of `sboxU` and installs the full `sboxU` module
+in your SAGE's python environment. You can then import `sboxU` like
+any other python module.
 
-This compiles the C++ part of `sboxU` and allows it to be called from
-a SAGE script. To use it in your project, simply move the `sboxU`
-folder to your project's directory. You can then import `sboxU` like
-any other python module.  As an example of the functions provided by
-`sboxU`, the SAGE script `example.py` stored alongside the folder
-`sboxU` generates random permutations and tests their affine
+### Installation via `nix`
+
+To create a development shell that contains SAGE with `sboxU` installed, use the following command:
+
+    nix develop github:lpp-crypto/sboxU#devShell.x86_64-linux
+
+## Example Usage
+
+As an example of the functions provided by `sboxU`, you can download and run the SAGE script [`example.py`](https://raw.githubusercontent.com/lpp-crypto/sboxU/refs/heads/master/example.py).
+There `sboxU` generates random permutations and tests their affine
 equivalence.
-
-Then, in order to use the functions provided by sboxU, simply
-paste/make a link to the folder sboxU from the directory in which you
-are working. For example, if you have a script called `test.py` in
-which you want to call the functions in sboxU then your directory
-should look like this:
-
-    $ ls
-    test.py
-    README.md
-    sboxu/
-
-and the file `test.py` should contain `from sboxU import *`. You can
-also import sboxU in a sage notebook session provided that you started
-sage from the folder containing it.
+
+On a unix based system (e.g. Linux or macOS), use the following commands:
+
+    wget https://raw.githubusercontent.com/lpp-crypto/sboxU/refs/heads/master/example.py
+    sage example.py
+
+
+To write your own script using `sboxU`, this file should contain `from sboxU import *`.
+You can also import sboxU in a sage notebook session.
 
 
 ## Troubleshooting

default.nix

@@ -0,0 +1,33 @@
+{
+  packageName,
+  packageVersion,
+
+  buildPythonPackage,
+
+  # build-system
+  gcc,
+  setuptools_scm,
+  cython,
+}:
+
+let
+in buildPythonPackage rec {
+  pname = packageName;
+  version = packageVersion;
+  pyproject = true;
+  build-system = [ setuptools_scm ];
+  src = ./.;
+
+  propagatedBuildInputs = [
+    gcc
+    cython
+  ];
+
+  # pythonImportsCheck = [ packageName ];  # we currently build using python and not sage, thus import checking is not possible
+
+  meta = {
+    description = "SAGE/Python functions useful for studying S-boxes and Boolean functions such as computing the DDT, computing the Walsh spectrum, affine equivalence testing...";
+    homepage = "https://github.com/lpp-crypto/sboxU";
+  };
+}
+

flake.nix

@@ -0,0 +1,54 @@
+{
+  description = "SAGE/Python functions useful for studying S-boxes and Boolean functions such as computing the DDT, computing the Walsh spectrum, affine equivalence testing...";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-24.05";
+  };
+
+  outputs = { self, nixpkgs }: let
+    system = "x86_64-linux";
+    pkgs = import nixpkgs { inherit system; };
+    packageName = "sboxU";
+    packageVersion = "1.3.0";
+  in {
+
+    packages."${system}" = {
+      "${packageName}" = pkgs.python3Packages.callPackage ./default.nix {
+        inherit packageName packageVersion;
+      };
+
+      default = self.packages."${system}"."${packageName}";
+
+      overlay = (final: prev: {
+        pythonPackagesExtensions = prev.pythonPackagesExtensions ++ [
+          (final: prev: {
+            "${packageName}" = self.packages."${system}".default;
+          })
+        ];
+      });
+    };
+
+    devShell."${system}" = let
+        pkgs = import nixpkgs {
+          inherit system;
+          overlays = [ self.packages."${system}".overlay ];
+        };
+
+	customSage = pkgs.sage.override {
+          requireSageTests = false;
+          extraPythonPackages = ps: with ps; [
+            ps."${packageName}"
+	  ];
+        };
+        customPython = with pkgs; (pkgs.sage.withPackages (ps: [
+          ps."${packageName}"
+        ]));
+
+        packages = [ customSage ];
+    in pkgs.mkShell {
+      inherit packages;
+    };
+
+  };
+}
+

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = [ "setuptools", "wheel", "cython" ]
+build-backend = "setuptools.build_meta"

sboxU/sboxU_cython/cpp_ccz.pyx

@@ -2,7 +2,7 @@
 # Time-stamp: <2023-12-05 10:36:16 leo>
 
 import os
-from sboxu_cpp_no_fp_lat cimport *
+from sboxU.sboxU_cython.sboxu_cpp_no_fp_lat cimport *
 from math import log
 
 

sboxU/sboxU_cython/cpp_diff_lin.pyx

@@ -5,7 +5,7 @@ import os
 from libcpp cimport bool
 from libcpp.vector cimport vector
 from libc.stdint cimport int64_t, uint64_t
-from sboxu_cpp cimport *
+from sboxU.sboxU_cython.sboxu_cpp cimport *
 import os
 from sage.all import Integer
 

sboxU/sboxU_cython/cpp_equiv.pyx

@@ -2,7 +2,7 @@
 # Time-stamp: <2023-01-04 15:57:08 lperrin>
 
 import os
-from sboxu_cpp_no_fp_lat cimport *
+from sboxU.sboxU_cython.sboxu_cpp_no_fp_lat cimport *
 
 def linear_equivalence_fast(l0, l1, all_mappings):
     return linear_equivalence_cpp(l0, l1, all_mappings)