From ccbba9ad838e6e05ee7c4e14eb38665e41244c62 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sun, 26 May 2024 14:53:26 +0200 Subject: [PATCH] split README --- README.md | 155 ++---------------- crates/servicepoint/Cargo.toml | 2 +- crates/servicepoint/README.md | 54 ++++++ crates/servicepoint_binding_c/Cargo.toml | 2 +- crates/servicepoint_binding_c/README.md | 63 +++++++ crates/servicepoint_binding_cs/Cargo.toml | 2 +- crates/servicepoint_binding_cs/README.md | 65 ++++++++ .../ServicePoint/ServicePoint.csproj | 2 +- 8 files changed, 199 insertions(+), 146 deletions(-) create mode 100644 crates/servicepoint/README.md create mode 100644 crates/servicepoint_binding_c/README.md create mode 100644 crates/servicepoint_binding_cs/README.md diff --git a/README.md b/README.md index b422c20..bae2ed9 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,31 @@ # servicepoint -[![crates.io](https://img.shields.io/crates/v/servicepoint.svg)](https://crates.io/crates/servicepoint) -[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint)](https://crates.io/crates/servicepoint) -[![docs.rs](https://img.shields.io/docsrs/servicepoint)](https://docs.rs/servicepoint/latest/servicepoint/) -[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint)](./LICENSE) - In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point Display" or "Airport Display". -This repository contains a library for parsing, encoding and sending packets to this display via UDP. +This repository contains a library for parsing, encoding and sending packets to this display via UDP in multiple +programming languages. -## Note on stability +Take a look at the contained crates for language specific information: -This library is still in early development. -You can absolutely use it, and it works, but expect minor breaking changes with every version bump. -Please specify the full version including patch in your Cargo.toml until 1.0 is released. - -Expect bugs and/or missing features in the language bindings for now. If you need something specific, open an issue or a pull request. - -## Rust - -This is where the library works the best. -Any API usage accepted by the compiler in a safe context is either safe or buggy (issues welcome) - -```bash -cargo add servicepoint -``` - -```rust -fn main() { - // establish connection - let connection = servicepoint::Connection::open("172.23.42.29:2342") - .expect("connection failed"); - - // clear screen content - connection.send(servicepoint::Command::Clear.into()) - .expect("send failed"); -} -``` - -More examples are available in the repository folder and in the [Projects using the library]() section - -## C / C++ - -The lowest common denominator. Things to keep in mind: - -- This is a chainsaw. You will cut your leg. -- function names are: `sp2_` \ \. -- Use the rust documentation. -- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free. -- Option or Result turn into nullable return values - check for NULL! -- There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable. -- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. - -```c++ -#include -#include "servicepoint.h" - -int main(void) { - sp2_Connection *connection = sp2_connection_open("localhost:2342"); - if (connection == NULL) - return 1; - - sp2_PixelGrid *pixels = sp2_pixel_grid_new(sp2_PIXEL_WIDTH, sp2_PIXEL_HEIGHT); - sp2_pixel_grid_fill(pixels, true); - - sp2_Command *command = sp2_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - sp2_Packet *packet = sp2_packet_from_command(command); - if (!sp2_connection_send(connection, packet)) - return 1; - - sp2_connection_dealloc(connection); - return 0; -} -``` - -## C# / F# - -Uses C bindings internally to provide a similar API to rust. Things to keep in mind: - -- You will get a `NullPointerException` when trying to call a method where the native instance has been consumed already (e.g. when `Send`ing a command instance twice). Send a clone instead of the original if you want to keep using it. -- Some lower-level APIs _will_ panic in native code when used improperly. - Example: manipulating the `Span` of an object after freeing the instance. -- C# specifics are documented in the library. Use the rust documentation for everything else. Naming and semantics are the same apart from CamelCase instead of kebab_case. -- You will only get rust backtraces in debug builds of the native code. -- F# is not explicitly tested. If there are usability or functionality problems, please open an issue. -- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. - -```csharp -using ServicePoint; - -// using statement calls Dispose() on scope exit, which frees unmanaged instances -using var connection = Connection.Open("127.0.0.1:2342"); -using var pixels = PixelGrid.New(Constants.PixelWidth, Constants.PixelHeight); - -while (true) -{ - pixels.Fill(true); - connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone())); - Thread.Sleep(5000); - - pixels.Fill(false); - connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone())); - Thread.Sleep(5000); -} -``` - -### Installation - -NuGet packages are not a good way to distribute native projects ([relevant issue](https://github.com/dotnet/sdk/issues/33845)). -Because of that, there is no NuGet package you can use directly. -Including this repository as a submodule and building from source is the recommended way of using the library. - -```bash -git submodule add https://github.com/kaesaecracker/servicepoint.git -git commit -m "add servicepoint submodule" -``` - -You can now reference `servicepoint-bindings-cs/src/ServicePoint.csproj` in your project. -The rust library will automatically be built. - -Please provide more information in the form of an issue if you need the build to copy a different library file for your platform. - -### Installation - -Copy the header to your project and compile against. - -You have the choice of linking statically (recommended) or dynamically. -- The C example shows how to link statically against the `staticlib` variant. -- When linked dynamically, you have to provide the `cdylib` at runtime in the _same_ version, as there are no API/ABI guarantees yet. - -## Features - -This library has multiple compression libraries as optional dependencies. -If you do not need compression/decompression support you can disable those features. -In the likely case you only need one of them, you can include that one specifically. - -```toml -[dependencies.servicepoint] -git = "https://github.com/kaesaecracker/servicepoint.git" -default-features = false -features = ["compression-bz"] -``` - -Language bindings will not know which features are available and may fail at runtime. -It is recommended to include all features for builds used outside of rust. +| Language | Readme | +|----------|---------------------------------------------------------------------| +| Rust | [servicepoint](crates/servicepoint/README.md) | +| C / C++ | [servicepoint_binding_c](crates/servicepoint_binding_c/README.md) | +| C# / F# | [servicepoint_binding_cs](crates/servicepoint_binding_cs/README.md) | ## Projects using the library -- screen simulator (rust): https://github.com/kaesaecracker/pixel-receiver-rs +- screen simulator (rust): https://github.com/kaesaecracker/servicepoint-simulator - tanks game (C#): https://github.com/kaesaecracker/cccb-tanks-cs +- cellular automata slideshow (rust): https://github.com/kaesaecracker/servicepoint-life To add yourself to the list, open a pull request. ## Where is servicepoint1? -This library is a spiritual mix of a not-yet-working rust library called `servicepoint` and a bunch of working but also unfinished C# code. Because most of the API concept and a bunch of code is taken from the rust library, the result is called `servicepoint`. +This library is a spiritual mix of a not-yet-working rust library called `servicepoint` and a bunch of working but also +unfinished C# code. Because most of the API concept and a bunch of code is taken from the rust library, the result is +called `servicepoint`. ## Contributing diff --git a/crates/servicepoint/Cargo.toml b/crates/servicepoint/Cargo.toml index 4b24f07..6ae0b0e 100644 --- a/crates/servicepoint/Cargo.toml +++ b/crates/servicepoint/Cargo.toml @@ -7,7 +7,7 @@ license = "GPL-3.0-or-later" description = "A rust library for the CCCB Service Point Display." homepage = "https://docs.rs/crate/servicepoint" repository = "https://github.com/cccb/servicepoint" -readme = "../../README.md" +readme = "README.md" [lib] crate-type = ["rlib"] diff --git a/crates/servicepoint/README.md b/crates/servicepoint/README.md new file mode 100644 index 0000000..9d7064b --- /dev/null +++ b/crates/servicepoint/README.md @@ -0,0 +1,54 @@ +# servicepoint + +[![crates.io](https://img.shields.io/crates/v/servicepoint.svg)](https://crates.io/crates/servicepoint) +[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint)](https://crates.io/crates/servicepoint) +[![docs.rs](https://img.shields.io/docsrs/servicepoint)](https://docs.rs/servicepoint/latest/servicepoint/) +[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint)](../../LICENSE) + +In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point +Display" or "Airport Display". +This crate contains a library for parsing, encoding and sending packets to this display via UDP. + +## Examples + +```rust +fn main() { + // establish connection + let connection = servicepoint::Connection::open("172.23.42.29:2342") + .expect("connection failed"); + + // clear screen content + connection.send(servicepoint::Command::Clear.into()) + .expect("send failed"); +} +``` + +More examples are available in the crate. +Execute `cargo run --example` for a list of available examples and `cargo run --example ` to run one. + +## Note on stability + +This library is still in early development. +You can absolutely use it, and it works, but expect minor breaking changes with every version bump. +Please specify the full version including patch in your Cargo.toml until 1.0 is released. + +## Installation + +```bash +cargo add servicepoint +``` + +## Features + +This library has multiple compression libraries as optional dependencies. +If you do not need compression/decompression support you can disable those features. +In the likely case you only need one of them, you can include that one specifically. + +```toml +[dependencies] +servicepoint = { version = "0.5.0", default-features = false, features = ["compression-bz"] } +``` + +## Everything else + +Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information. diff --git a/crates/servicepoint_binding_c/Cargo.toml b/crates/servicepoint_binding_c/Cargo.toml index cc938d1..4146255 100644 --- a/crates/servicepoint_binding_c/Cargo.toml +++ b/crates/servicepoint_binding_c/Cargo.toml @@ -7,7 +7,7 @@ license = "GPL-3.0-or-later" description = "C bindings for the servicepoint crate." homepage = "https://docs.rs/crate/servicepoint" repository = "https://github.com/cccb/servicepoint" -readme = "../../README.md" +readme = "README.md" links = "servicepoint" [lib] diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md new file mode 100644 index 0000000..1a86753 --- /dev/null +++ b/crates/servicepoint_binding_c/README.md @@ -0,0 +1,63 @@ +# servicepoint_binding_c + +[![crates.io](https://img.shields.io/crates/v/servicepoint_binding_c.svg)](https://crates.io/crates/servicepoint) +[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint_binding_c)](https://crates.io/crates/servicepoint) +[![docs.rs](https://img.shields.io/docsrs/servicepoint_binding_c)](https://docs.rs/servicepoint/latest/servicepoint/) +[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint_binding_c)](../../LICENSE) + +In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point +Display" or "Airport Display". +This crate contains C bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP. + +## Examples + +```c++ +#include +#include "servicepoint.h" + +int main(void) { + sp2_Connection *connection = sp2_connection_open("localhost:2342"); + if (connection == NULL) + return 1; + + sp2_PixelGrid *pixels = sp2_pixel_grid_new(sp2_PIXEL_WIDTH, sp2_PIXEL_HEIGHT); + sp2_pixel_grid_fill(pixels, true); + + sp2_Command *command = sp2_command_bitmap_linear_win(0, 0, pixels, Uncompressed); + sp2_Packet *packet = sp2_packet_from_command(command); + if (!sp2_connection_send(connection, packet)) + return 1; + + sp2_connection_dealloc(connection); + return 0; +} +``` + +A full example including Makefile is available as part of this crate. + +## Note on stability + +This library is still in early development. +You can absolutely use it, and it works, but expect minor breaking changes with every version bump. +Please specify the full version including patch in your Cargo.toml until 1.0 is released. + +## Installation + +Copy the header to your project and compile against. + +You have the choice of linking statically (recommended) or dynamically. +- The C example shows how to link statically against the `staticlib` variant. +- When linked dynamically, you have to provide the `cdylib` at runtime in the _same_ version, as there are no API/ABI guarantees yet. + +## Notes on differences to rust library + +- function names are: `sp2_` \ \. +- Use the rust documentation. +- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free. +- Option or Result turn into nullable return values - check for NULL! +- There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable. +- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. + +## Everything else + +Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information. diff --git a/crates/servicepoint_binding_cs/Cargo.toml b/crates/servicepoint_binding_cs/Cargo.toml index f43abe2..7282c1d 100644 --- a/crates/servicepoint_binding_cs/Cargo.toml +++ b/crates/servicepoint_binding_cs/Cargo.toml @@ -3,7 +3,7 @@ name = "servicepoint_binding_cs" version.workspace = true edition = "2021" publish = false -readme = "../../README.md" +readme = "README.md" [lib] crate-type = ["cdylib"] diff --git a/crates/servicepoint_binding_cs/README.md b/crates/servicepoint_binding_cs/README.md new file mode 100644 index 0000000..1248af7 --- /dev/null +++ b/crates/servicepoint_binding_cs/README.md @@ -0,0 +1,65 @@ +# ServicePoint + +In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point +Display" or "Airport Display". +This crate contains C# bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP. + +## Examples + +```csharp +using ServicePoint; + +// using statement calls Dispose() on scope exit, which frees unmanaged instances +using var connection = Connection.Open("127.0.0.1:2342"); +using var pixels = PixelGrid.New(Constants.PixelWidth, Constants.PixelHeight); + +while (true) +{ + pixels.Fill(true); + connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone())); + Thread.Sleep(5000); + + pixels.Fill(false); + connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone())); + Thread.Sleep(5000); +} +``` + +A full example including project files is available as part of this crate. + +## Note on stability + +This library is still in early development. +You can absolutely use it, and it works, but expect minor breaking changes with every version bump. + +## Installation + +NuGet packages are not a good way to distribute native projects ([relevant issue](https://github.com/dotnet/sdk/issues/33845)). +Because of that, there is no NuGet package you can use directly. +Including this repository as a submodule and building from source is the recommended way of using the library. + +```bash +git submodule add https://github.com/kaesaecracker/servicepoint.git +git commit -m "add servicepoint submodule" +``` + +You can now reference `servicepoint-bindings-cs/src/ServicePoint.csproj` in your project. +The rust library will automatically be built. + +Please provide more information in the form of an issue if you need the build to copy a different library file for your platform. + +## Notes on differences to rust library + +Uses C bindings internally to provide a similar API to rust. Things to keep in mind: + +- You will get a `NullPointerException` when trying to call a method where the native instance has been consumed already (e.g. when `Send`ing a command instance twice). Send a clone instead of the original if you want to keep using it. +- Some lower-level APIs _will_ panic in native code when used improperly. + Example: manipulating the `Span` of an object after freeing the instance. +- C# specifics are documented in the library. Use the rust documentation for everything else. Naming and semantics are the same apart from CamelCase instead of kebab_case. +- You will only get rust backtraces in debug builds of the native code. +- F# is not explicitly tested. If there are usability or functionality problems, please open an issue. +- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. + +## Everything else + +Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information. diff --git a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj index e82c589..30778d0 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj +++ b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj @@ -56,7 +56,7 @@ - +