Merge pull request #29 from althonos/master

Find extensions and automatically generate Cargo.toml manifests

Author: althonos

.travis.yml

@@ -21,4 +21,5 @@ install:
   - pip install -e .
 
 script:
-  - cd example && python setup.py develop
+  - cd example && python setup.py develop && cd ..
+  - cd example_tomlgen && python setup.py tomlgen_rust -w && cd ..

CHANGES.rst

@@ -1,6 +1,12 @@
 CHANGES
 ^^^^^^^
 
+0.9.0 (2018-03-07)
+------------------
+
+- Find inplace extensions and automatically generate ``Cargo.toml`` manifests #29
+
+
 0.8.4 (2018-02-27)
 ------------------
 

example_tomlgen/.gitignore

@@ -0,0 +1,3 @@
+build/
+Cargo.toml
+Cargo.lock

example_tomlgen/README.rst

@@ -0,0 +1,121 @@
+`example_tomlgen`
+=================
+
+An example extensions with automatically generated ``Cargo.toml`` manifest
+files. Simply run ``python setup.py tomlgen_rust`` to generate the following
+files:
+
+* ``Cargo.toml`` for ``hello.english``
+
+.. code-block:: toml
+
+    [package]
+    name = "hello.english"
+    version = "0.1.0"
+    authors = ["Martin Larralde <[email protected]>"]
+    publish = false
+
+    [lib]
+    crate-type = ["cdylib"]
+    name = "hello_english"
+    path = "lib.rs"
+
+    [dependencies]
+    pyo3 = { version = "*", features = ["extension-module"] }
+    english-lint = "*"
+
+
+* ``Cargo.toml`` for ``hello.french``
+
+.. code-block:: toml
+
+    [package]
+    name = "hello.french"
+    version = "0.1.0"
+    authors = ["Martin Larralde <[email protected]>"]
+    publish = false
+
+    [lib]
+    crate-type = ["cdylib"]
+    name = "hello_french"
+    path = "lib.rs"
+
+    [dependencies]
+    pyo3 = { version = "*", features = ["extension-module"] }
+
+
+Metadata
+--------
+
+The package name will be generated from the position of the extension within
+the Python package. The same version is used as the one declared in ``setup.py``
+or ``setup.cfg``.
+
+The authors list is generated after the ``author`` and ``author_email`` options
+from ``setup.py`` / ``setup.cfg``, but can also be overriden using the
+``authors`` key in the ``[tomlgen_rust]`` section of ``setup.cfg``:
+
+.. code-block:: ini
+
+    [tomlgen_rust]
+    authors =
+      Jane Doe <[email protected]>
+      John Doe <[email protected]>
+
+The library name is a slugified variant of the extension package name, to
+avoid name collisions within the build directory.
+
+As a safety, ``publish = false`` is added to the ``[package]`` section
+(you wouldn't publish an automatically generated package, *would you ?!*).
+
+
+Options
+-------
+
+Use ``--force`` (or add ``force = true`` to the ``[tomlgen_rust]`` section of
+``setup.cfg``) to force generating a manifest even when one already exists.
+
+Use ``--create-workspace`` to create a virtual manifest at the root of your
+project (next to the ``setup.py`` file) which registers all of the extensions.
+This way, generic ``cargo`` commands can be run without leaving the root of
+the project.
+
+If ``--create-workspace`` is enable, a `.cargo/config` file will also be
+created to force ``cargo`` to build to the temporary build directory. Use
+``--no-config`` to disable.
+
+
+Dependencies
+------------
+
+To specify dependencies for all extensions, add them to the
+``[tomlgen_rust.dependencies]`` section of your setuptools configuration file
+(``setup.cfg``), as you would normally in your ``Cargo.toml`` file. Here is
+probably a good place to add ``pyo3`` as a dependency.
+
+To specify per-extension dependency, create a section for each extension
+(``[tomlgen_rust.dependencies.<DOTTEDPATH>]``, where ``<DOTTEDPATH>`` is the
+complete Python path to the extension (e.g. ``hello.english``). Extension
+specific dependencies are added *after* global dependencies.
+
+*Note that, since all projects are built in the same directory, you can also
+declare all dependencies in the* ``[tomlgen_rust.dependencies]``, *as they will
+be built only once anyway*.
+
+
+Automatic generation at each build
+----------------------------------
+
+If you intend to regenerate manifests everytime the library is built, you can
+add ``Cargo.toml`` and ``Cargo.lock`` to your ``.gitignore`` file.
+
+Then, make sure ``tomlgen_rust`` is run before ``build_rust`` everytime by
+adding aliases to your ``setup.cfg`` file:
+
+.. code-block:: ini
+
+    [aliases]
+    build_rust = tomlgen_rust -f build_rust
+    clean_rust = tomlgen_rust -f clean_rust
+    build = tomlgen_rust -f build
+    clean = clean_rust -f clean

example_tomlgen/hello/__init__.py

@@ -0,0 +1,4 @@
+# coding: utf-8
+
+from . import french
+from . import english

example_tomlgen/hello/english/lib.rs

@@ -0,0 +1,18 @@
+#![feature(proc_macro)]
+
+extern crate pyo3;
+
+use pyo3::prelude::*;
+
+/// Module documentation string
+#[py::modinit(english)]
+fn init(py: Python, m: &PyModule) -> PyResult<()> {
+
+    #[pyfn(m, "hello")]
+    fn hello(_py: Python) -> PyResult<()> {
+        println!("Hello, world!");
+        Ok(())
+    }
+
+    Ok(())
+}

example_tomlgen/hello/french/lib.rs

@@ -0,0 +1,18 @@
+#![feature(proc_macro)]
+
+extern crate pyo3;
+
+use pyo3::prelude::*;
+
+/// Module documentation string
+#[py::modinit(french)]
+fn init(py: Python, m: &PyModule) -> PyResult<()> {
+
+    #[pyfn(m, "hello")]
+    fn hello(_py: Python) -> PyResult<()> {
+        println!("Bonjour, monde!");
+        Ok(())
+    }
+
+    Ok(())
+}

example_tomlgen/setup.cfg

@@ -0,0 +1,22 @@
+[metadata]
+author_email = "[email protected]"
+description = Example Python/Rust project with automatic Cargo.toml generation
+long-description = file: README.rst
+
+[options]
+zip_safe = false
+
+[tomlgen_rust]
+create_workspace = true
+
+[tomlgen_rust.dependencies]
+pyo3 = { version = "*", features = ["extension-module"] }
+
+[tomlgen_rust.dependencies.hello.english]
+english-lint = "*"
+
+[aliases]
+build_rust = tomlgen_rust build_rust
+clean_rust = tomlgen_rust clean_rust
+build = tomlgen_rust build
+clean = clean_rust clean

example_tomlgen/setup.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+import setuptools
+import setuptools_rust as rust
+
+
+setuptools.setup(
+    name='hello-rust',
+    version='0.1.0',
+    author="Martin Larralde",
+
+    # Find all inplace extensions
+    rust_extensions=rust.find_rust_extensions(
+        binding=rust.Binding.PyO3,
+        strip=rust.Strip.Debug,
+    ),
+
+    # specify setup dependencies
+    setup_requires=[
+        'setuptools',
+        'setuptools_rust',
+    ],
+
+    # rust extensions are not zip safe, just like C-extensions.
+    zip_safe=False
+)

setup.py

@@ -38,5 +38,6 @@
     build_ext=setuptools_rust:build_ext
     build_rust=setuptools_rust:build_rust
     test_rust=setuptools_rust:test_rust
+    tomlgen_rust=setuptools_rust:tomlgen_rust
     """
 )