mirror of
https://git.proxmox.com/git/perlmod
synced 2025-11-03 20:09:32 +00:00
92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
perlmod
|
|
=======
|
|
|
|
This is a rust crate which allows exporting rust modules as perl packages.
|
|
|
|
The initial use case for this was to help migrating a perl codebase to rust.
|
|
|
|
This crate can be compared to perl xs, however, it does not expose the complete power of perl, only
|
|
enough to make callable methods. The biggest part is the serde serializer and deserializer,
|
|
providing ways to transfer data between perl and rust.
|
|
|
|
State of this crate
|
|
===================
|
|
|
|
This crate is functional and supports a subset perl that the authors consider "sane enough" to work
|
|
with. It may misbehave when faced with dark perl magic (technical term), but should be enough for a
|
|
lot of use cases.
|
|
|
|
This crate is being used by Proxmox to implement parts of Proxmox VE and Proxmox Mail Gateway, and
|
|
is being maintained as part of these products.
|
|
|
|
Change Logs
|
|
===========
|
|
|
|
Since we maintain debian build scripts, see the `debian/changelog` files in `proxmox/` and
|
|
`proxmox-macro/` for their respective changes.
|
|
|
|
Where to report bugs
|
|
====================
|
|
|
|
https://bugzilla.proxmox.com
|
|
|
|
Licensing, linking to libperl and adding more features
|
|
======================================================
|
|
|
|
The perl license explicitly states that code linking to the perl library for the purpose of merely
|
|
providing subroutines or variables is considered part of its "input", provided it does not change
|
|
the language in any way that would cause it to fail its regression tests. It does not consider its
|
|
"input" to fall under perl's copyright.
|
|
|
|
In order to avoid confusion about licensing or copyright, this crate does not aim to provide
|
|
complete interoperability, but is meant merely as an alternative to using "xs" for writing bindings
|
|
to rust code.
|
|
|
|
Features which would allow changing this (other than by obviously unintended behavior (such as
|
|
bugs, raw memory access, etc.)) will not be accepted into this crate and will need to be maintained
|
|
elsewhere.
|
|
|
|
Pending Changes before 1.0
|
|
==========================
|
|
|
|
* Make some kind of perl-package-generation tool for generating the `.pm`
|
|
files, we only need to call bootstrap functions after all.
|
|
(So we may not even need to parse the rust code, rather, just provide a list
|
|
of perl packages to create...)
|
|
|
|
Current recommended usage.
|
|
==========================
|
|
|
|
## "Blessed" objects.
|
|
|
|
```rust
|
|
#[perlmod::package(name = "My::Pkg")]
|
|
mod export {
|
|
use perlmod::{Error, Value};
|
|
|
|
// Create the common defaults used for blessed objects with attached magic pointer for rust:
|
|
perlmod::declare_magic!(Box<MyPkg> : &MyPkg as "My::Pkg");
|
|
|
|
struct MyPkg {
|
|
content: String,
|
|
}
|
|
|
|
impl Drop for MyPkg {
|
|
fn drop(&mut self) {
|
|
println!("Dropping blessed MyPkg with content {:?}", self.content);
|
|
}
|
|
}
|
|
|
|
#[export(raw_return)]
|
|
fn new(#[raw] class: Value, content: String) -> Result<Value, Error> {
|
|
Ok(perlmod::instantiate_magic!(&class, MAGIC => Box::new(MyPkg { content })))
|
|
}
|
|
|
|
#[export]
|
|
fn call(#[try_from_ref] this: &MyPkg, param: &str) -> Result<(), Error> {
|
|
println!("Calling magic with content {:?}, with parameter {}", this.content, param);
|
|
Ok(())
|
|
}
|
|
}
|
|
```
|