clippy fixups
[perlmod.git] / 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 ```