README.md

   1 perlmod
   2 =======
   3
   4 This is a rust crate which allows exporting rust modules as perl packages.
   5
   6 The initial use case for this was to help migrating a perl codebase to rust.
   7
   8 This crate can be compared to perl xs, however, it does not expose the complete power of perl, only
   9 enough to make callable methods. The biggest part is the serde serializer and deserializer,
  10 providing ways to transfer data between perl and rust.
  11
  12 State of this crate
  13 ===================
  14
  15 This crate is functional and supports a subset perl that the authors consider "sane enough" to work
  16 with. It may misbehave when faced with dark perl magic (technical term), but should be enough for a
  17 lot of use cases.
  18
  19 This crate is being used by Proxmox to implement parts of Proxmox VE and Proxmox Mail Gateway, and
  20 is being maintained as part of these products.
  21
  22 Change Logs
  23 ===========
  24
  25 Since we maintain debian build scripts, see the `debian/changelog` files in `proxmox/` and
  26 `proxmox-macro/` for their respective changes.
  27
  28 Where to report bugs
  29 ====================
  30
  31 https://bugzilla.proxmox.com
  32
  33 Licensing, linking to libperl and adding more features
  34 ======================================================
  35
  36 The perl license explicitly states that code linking to the perl library for the purpose of merely
  37 providing subroutines or variables is considered part of its "input", provided it does not change
  38 the language in any way that would cause it to fail its regression tests. It does not consider its
  39 "input" to fall under perl's copyright.
  40
  41 In order to avoid confusion about licensing or copyright, this crate does not aim to provide
  42 complete interoperability, but is meant merely as an alternative to using "xs" for writing bindings
  43 to rust code.
  44
  45 Features which would allow changing this (other than by obviously unintended behavior (such as
  46 bugs, raw memory access, etc.)) will not be accepted into this crate and will need to be maintained
  47 elsewhere.
  48
  49 Pending Changes before 1.0
  50 ==========================
  51
  52 * Make some kind of perl-package-generation tool for generating the `.pm`
  53   files, we only need to call bootstrap functions after all.
  54   (So we may not even need to parse the rust code, rather, just provide a list
  55   of perl packages to create...)
  56
  57 Current recommended usage.
  58 ==========================
  59
  60 ## "Blessed" objects.
  61
  62 ```rust
  63 #[perlmod::package(name = "My::Pkg")]
  64 mod export {
  65     use perlmod::{Error, Value};
  66
  67     // Create the common defaults used for blessed objects with attached magic pointer for rust:
  68     perlmod::declare_magic!(Box<MyPkg> : &MyPkg as "My::Pkg");
  69
  70     struct MyPkg {
  71         content: String,
  72     }
  73
  74     impl Drop for MyPkg {
  75         fn drop(&mut self) {
  76             println!("Dropping blessed MyPkg with content {:?}", self.content);
  77         }
  78     }
  79
  80     #[export(raw_return)]
  81     fn new(#[raw] class: Value, content: String) -> Result<Value, Error> {
  82         Ok(perlmod::instantiate_magic!(&class, MAGIC => Box::new(MyPkg { content })))
  83     }
  84
  85     #[export]
  86     fn call(#[try_from_ref] this: &MyPkg, param: &str) -> Result<(), Error> {
  87         println!("Calling magic with content {:?}, with parameter {}", this.content, param);
  88         Ok(())
  89     }
  90 }
  91 ```