Update CHANGELOG, README and Cargo.toml for v0.2.0 release

kellerkindt · Feb 3, 2021 · bd43b6e · bd43b6e
1 parent 8290a8e
commit bd43b6e
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 81 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,64 +1,47 @@
-# 0.2.0-alpha3 (Oct 14, 2020)
-
-### Fixes
-- Missing CI checks on non-default features
-
-### Added
-- Support for `SET`s and `SET OF`s\*
-- Support for extensible `SET`s
-- Support for `SIZE` constraints for `SET OF`s
-- `TagResolver` to properly resolve Tags of ASN.1 types 
-- `syn::common::Constraint` which has `const TAG: Tag` and implementation for all generated constraint types 
-
-\* For `SET OF` only BASIC-PER encoding is supported currently, see [#20](https://github.com/kellerkindt/asn1rs/issues/20)
-
-### Changes
-- The ASN.1 `OPTIONAL` type is now represented as `optional` instead of `option` in `#[asn(..)]`
-- The protobuf serializer is now optional and can be enabled with the `protobuf` feature flag
-
-# 0.2.0-alpha2 (Sep 03, 2020)
+# Version 0.2.0 (2021-02-03)
 
 This release includes a lot of refactoring and new features.
 With these changes, it is now possible to use the following two ASN.1 standards:
 
- - 🎉 ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) ts(102894) cdd(2) version(1)``` (ITS-Container)
- - 🎉 ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) en(302637) cam(2) version(1)``` (CAM-PDU-Descriptions)
+- 🎉 ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) ts(102894) cdd(2) version(1)``` (ITS-Container)
+- 🎉 ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) en(302637) cam(2) version(1)``` (CAM-PDU-Descriptions)
 
+The serialization and deserialization process was completely revamped to replace the code generation that uses string concatenation and instead utilize (smaller) proc-macros and types for it.
+The previous - now called legacy codegen - is still available, but deprecated and hidden behind the `legacy-uper-codegen` and `legacy-protobuf-codegen` feature.
+It will be **removed in 0.3.0**.
+
+Feel free to visit [the tests](tests) to learn about the new usage. You might want to start with the [showcase].
 
 ### Fixes
+- lots of smaller and niche parsing errors
 - Implement the canonical order for tags (ITU-T X.680 | ISO/IEC 8824-1, 8.6)
+- Missing CI checks on non-default features
 
 ### Added
+- support for ASN-extensible `CHOICE` and `ENUMERATED` types
+- `Reader`, `Writer` traits to (de)serialize based on the visitor pattern, asn attribute annotation, see [showcase] and [proc_macro_attribute]. This will allow further ASN encodings to be implemented without further code generation (to be clear, this not on the roadmap for now, but PRs are welcome).
 - Support for `INTEGER` constants
 - Support for extensible `SEQUENCE`s
 - Support for extensible `INTEGER`s
 - Support for `BIT STRING`, as well as the `SIZE` constraint, constants, and the extensible flag
 - Support for `IA5String`, as well as the `SIZE` constraint, and the extensible flag
 - Support for `SIZE` constraints for `OCTET STRING`s
 - Support for `SIZE` constraints for `UTF8String`s
-- Support for `SIZE` constraints for `SEQUENCE OF`s
-- ASN.1 Support Overview to README
-
-### Changes
-- Parse/Accept ObjectIdentifier in `FROM` directives and module definitions
-- The whole module `crate::io::uper` is now **deprecated**
-- Reimplemented all low level uPER functions - this time strictly according to specification and using names mentioned there, see ```crate::io::per```
-- Better prepare for alternative encoding rules (especially aligned PER, although this is no specific goal)
-- Help the compiler in figuring out where const evaluations are possible (see `const_*!` macros)
-- Lots of `#[inline]` hinting 
+- Support for `SIZE` constraints for `SEQUENCE OF`s 
+- Support for `SET`s and `SET OF`s\*
+- Support for extensible `SET`s
+- Support for `SIZE` constraints for `SET OF`s
+- `TagResolver` to properly resolve Tags of ASN.1 types 
+- `syn::common::Constraint` which has `const TAG: Tag` and implementation for all generated constraint types
+- CI checks for specific feature combinations
 
 
-# 0.2.0-alpha1 (May 13, 2020)
 
-### Fixes
-- lots of smaller and niche parsing errors
-
-### Added
-- support for ASN-extensible `CHOICE` and `ENUMERATED` types  
-- `Reader`, `Writer` traits to (de)serialize based on the visitor pattern, asn attribute annotation, see [showcase] and [proc_macro_attribute]. This will allow further ASN encodings to be implemented without further code generation (to be clear, this not on the roadmap for now, but PRs are welcome).
+\* For `SET OF` only BASIC-PER encoding is supported currently, see [#20](https://github.com/kellerkindt/asn1rs/issues/20)
 
 ### Changes
-- deprecated `UperSerializer` which generates a lot of complex code for (uper-)serialization. Instead general purpose and less complex code that is based on the visitor pattern will be generated. See [showcase] and commits linked to [#11]. This also allows to write ASN serializable structures without writing ASN itself (see [proc_macro_attribute]):
+- Added ASN.1 Support Overview to README
+- Deprecated `UperSerializer` which generates a lot of complex code for (uper-)serialization. Instead general purpose and less complex code that is based on the visitor pattern will be generated. See [showcase] and commits linked to [#11]. This also allows to write ASN serializable structures without writing ASN itself (see [proc_macro_attribute]):
 
 ```rust
 #[asn(sequence)]
@@ -87,6 +70,15 @@ fn pizza_test_uper_1() {
 }
 
 ```
+- Parse/Accept ObjectIdentifier in `FROM` directives and module definitions
+- The module `crate::io::uper` is now **deprecated**
+- Reimplemented all low level uPER functions - this time strictly according to specification and using names mentioned there, see ```crate::io::per```
+- Better prepare for alternative encoding rules (especially aligned PER, although this is no specific goal)
+- Help the compiler in figuring out where const evaluations are possible (see `const_*!` macros)
+- Lots of `#[inline]` hinting
+- The ASN.1 `OPTIONAL` type is now represented as `optional` instead of `option` in `#[asn(..)]`
+- The protobuf serializer is now optional and can be enabled with the `protobuf` feature flag
+- Deprecated `Protobuf` trait which is replaced by `ProtobufReader` and `ProtobufWriter` that use the common `Readable` and `Writable` traits
 
 [showcase]: tests/showcase.rs
 [proc_macro_attribute]: tests/basic_proc_macro_attribute.rs

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "asn1rs"
-version = "0.2.0-alpha3"
+version = "0.2.0"
 authors = ["Michael Watzko <[email protected]>"]
 edition = "2018"
 description = "ASN.1 to Rust, Protobuf and SQL compiler/code generator. Supports ASN.1 UPER"
@@ -44,8 +44,8 @@ futures = { version = "0.3.4", optional = true }
 bytes = { version = "0.5.4", optional = true }
 
 # feature asn1rs-*
-asn1rs-model =  { version = "0.2.0-alpha3", path = "asn1rs-model", optional = true }
-asn1rs-macros = { version = "0.2.0-alpha3", path = "asn1rs-macros", optional = true }
+asn1rs-model =  { version = "0.2.0", path = "asn1rs-model", optional = true }
+asn1rs-macros = { version = "0.2.0", path = "asn1rs-macros", optional = true }
 
 [dev-dependencies]
 syn = {version = "1.0.28", features = ["full"] }

diff --git a/README.md b/README.md
@@ -1,9 +1,10 @@
 # asn1rs - ASN.1 Compiler for Rust
 
 This crate generates Rust Code and optionally compatible Protobuf and SQL schema files from ASN.1 definitions.
-Basic support for [serde](https://crates.io/crates/serde) integration is provided.
+Integration with [serde](https://crates.io/crates/serde) is supported.
+
 The crate can be used as standalone CLI binary or used as library through its API
-(for example inside the ```build.rs``` script).
+(for example inside your ```build.rs``` script).
 
 
 [![Build Status](https://github.com/kellerkindt/asn1rs/workflows/Rust/badge.svg)](https://github.com/kellerkindt/asn1rs/actions?query=workflow%3ARust)
@@ -14,12 +15,8 @@ The crate can be used as standalone CLI binary or used as library through its AP
 
 
 
-#### Support Table
+### Supported Features
 
-**TLDR**
-  - The legacy UPER Reader/Writer does not support all features (pre v0.2.0)
-  - Protobuf, sync and async PSQL ignore most constraints
-  - The new (v0.2.0) UPER Reader/Writer supports all listed features
 
 | Feature             | Parses  | UPER    | Protobuf    | PSQL        | Async PSQL | UPER Legacy\*     |
 | --------------------|:--------|:--------|:------------|:------------|:-----------|------------------:|
@@ -67,13 +64,20 @@ The crate can be used as standalone CLI binary or used as library through its AP
  - ❌ ub: undefined behavior - whatever seems reasonable to prevent compiler errors and somehow transmit the value
  - 🟥 error: fails to compile / translate
 
-\*The legacy UPER Reader/Writer is deprecated and will be removed in or before v0.3.0
+\*The legacy UPER Reader/Writer is deprecated and will be removed in version 0.3.0
 
-##### Supported standards
- - ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) ts(102894) cdd(2) version(1)``` (ITS-Container)
- - ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) en(302637) cam(2) version(1)``` (CAM-PDU-Descriptions)
+**TLDR**
+- The new (v0.2.0) UPER Reader/Writer supports all listed features
+- Protobuf, sync&async PSQL ignore most constraints
+- The legacy UPER Reader/Writer does not support all features (pre v0.2.0)
 
-#### CLI usage
+#### Supported standards
+ -  [ETSI TS 102 894-2 / ITS-Container](https://www.etsi.org/deliver/etsi_ts/102800_102899/10289402/01.02.01_60/ts_10289402v010201p.pdf): \
+    ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) ts(102894) cdd(2) version(1)```
+ -  [ETSI EN 302 637-2 / ITS-CAM](https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.03.01_30/en_30263702v010301v.pdf): \
+    ```itu-t(0) identified-organization(4) etsi(0) itsDomain(5) wg1(1) en(302637) cam(2) version(1)```
+
+### CLI usage
 
 It is always helpful to check ```asn1rs --help``` in advance.
 The basic usage can be seen blow:
@@ -90,11 +94,11 @@ asn1rs -t proto directory/for/protobuf/files some.asn1 messages.asn1
 asn1rs -t sql directory/for/sql/schema/files some.asn1 messages.asn1
 ```
 
-#### API usage
+### Example: build.rs
 
-The following example generates Rust, Protobuf and SQL files for all ```.asn1```-files in the ```asn/``` directory of the project.
+The following example generates Rust, Protobuf and SQL files for all ```.asn1```-files in the ```asn/``` directory of a workspace.
 While the generated Rust code is written to the ```src/``` directory, the Protobuf files are written to ```proto/``` and the SQL files are written to ```sql/ ```.
-Additionally, in this example each generated Rust-Type also receives ```Serialize``` and ```Deserialize``` derive directives (```#[derive(Serialize, Deserialize)]```) for automatic [serde](https://crates.io/crates/serde) integration.
+Additionally, in this example each generated Rust-Type also receives ```Serialize``` and ```Deserialize``` derive directives (```#[derive(Serialize, Deserialize)]```) for [serde](https://crates.io/crates/serde) integration.
 
 Sample ```build.rs``` file:
 
@@ -124,8 +128,8 @@ pub fn main() {
                 .filter(|entry| entry.ends_with(".asn1"))
         })
         .for_each(|path| {
+            println!("cargo:rerun-if-changed={}", path);
             if let Err(e) = converter.load_file(&path) {
-                println!("cargo:rerun-if-changed={}", path);
                 panic!("Loading of .asn1 file failed {}: {:?}", path, e);
             }
         });
@@ -157,9 +161,9 @@ pub fn main() {
 
 ```
 
-#### Inlining ASN.1 with procedural macros
+### Example: Inlining ASN.1 with procedural macros
 
-Minimal example by inlining the ASN.1 definition. For more examples, see ```tests/```.
+Minimal example by inlining the ASN.1 definition. For more examples see [tests/](tests).
 ```rust
 use asn1rs::prelude::*;
 
@@ -191,7 +195,7 @@ fn test_write_read() {
 #[test]
 fn test_constraint_eq() {
     // these types should normally not be accessed, but in this exampled they show
-    // the way the ASN.1 constraints are encoded in to the struct type constraints.
+    // the way the ASN.1 constraints are encoded with the Rust type system.
     use asn1rs::syn::numbers::Constraint;
     assert_eq!(
         ___asn1rs_RangedMaxField0Constraint::MIN,
@@ -205,7 +209,7 @@ fn test_constraint_eq() {
 ```
 
 
-#### Example ASN.1-Definition to Rust, Protobuf and SQL
+### Example: ASN.1-Definition converted to Rust, Protobuf and SQL
 
 Minimal example showcasing what is being generated from an ASN.1 definition:
 
@@ -231,25 +235,21 @@ pub struct Header {
     #[asn(integer(0..1209600000))] pub timestamp: u32,
 }
 
-// OPTIONAL: Insert and query functions for async PostgreSQL
+// only with the feature "async-psql": Insert and query functions for async PostgreSQL
 impl Header {
     pub async fn apsql_retrieve_many(context: &apsql::Context<'_>, ids: &[i32]) -> Result<Vec<Self>, apsql::Error> { /*..*/ }
     pub async fn apsql_retrieve(context: &apsql::Context<'_>, id: i32) -> Result<Self, apsql::Error> { /*..*/ }
     pub async fn apsql_load(context: &apsql::Context<'_>, row: &apsql::Row) -> Result<Self, apsql::Error> { /*..*/ }
     pub async fn apsql_insert(&self, context: &apsql::Context<'_>) -> Result<i32, apsql::PsqlError> { /*..*/ }
 }
 
-// OPTIONAL: Serialize and deserialize functions for protobuf
-impl ProtobufEq for Header { /*..*/ }
-impl Protobuf for Header { /*..*/ }
-
-// OPTIONAL: Insert and query functions for non-async PostgreSQL
+// only with the feature "psql": Insert and query functions for non-async PostgreSQL
 impl PsqlRepresentable for Header { /*..*/ }
 impl PsqlInsertable for Header { /*..*/ }
 impl PsqlQueryable for Header { /*..*/ }
 ```
 
-OPTIONAL: The generated protobuf file:
+The generated protobuf file (optional):
 
 ```proto
 syntax = 'proto3';
@@ -260,7 +260,7 @@ message Header {
 }
 ```
 
-OPTIONAL: The generated (p)sql file:
+The generated SQL file (optional):
 
 ```sql
 DROP TABLE IF EXISTS Header CASCADE;
@@ -271,11 +271,11 @@ CREATE TABLE Header (
 );
 ```
 
-#### Example usage of async postgres
+#### Example: Usage of async postgres
 NOTE: This requires the `async-psql` feature.
 
-Using async postgres allows the message - or the batched messages - to take advantage of [`pipelining`] automatically.
-This can provide a speedup (personal experience: at around 26%) compared to the synchronous/blocking postgres implementation.
+Using async postgres allows the message - or the batched messages - to take advantage of [`pipelining`].
+This can provide a significant speedup for deep message types (personal experience this is around 26%) compared to the synchronous/blocking postgres implementation.
 
 ```rust
 use asn1rs::io::async_psql::*;
@@ -342,7 +342,7 @@ async fn main() {
 }
 ```
 
-#### Raw uPER usage
+#### Example: Raw uPER usage
 The module ```asn1rs::io``` exposes (de-)serializers and helpers for direct usage without ASN.1 definition:
 ```rust
 use asn1rs::prelude::*;
@@ -355,7 +355,7 @@ buffer.write_utf8_string("My UTF8 Text").unwrap();
 send_to_another_host(buffer.into::<Vec<u8>>()):
 ```
 
-#### Raw Protobuf usage
+#### Example: Raw Protobuf usage
 The module ```asn1rs::io::protobuf``` exposes (de-)serializers for protobuf usage:
 ```rust
 use asn1rs::io::protobuf::*;
@@ -372,10 +372,10 @@ send_to_another_host(buffer):
 Things to do at some point in time (PRs are welcome)
 
   - generate a proper rust module hierarchy from the modules' object-identifier
-  - remove legacy rust+uper code generator (probably in 0.3)
+  - remove legacy rust+uper code generator (v0.3.0)
   - support ```#![no_std]```
-  - refactor / clean-up (rust) code-generators
-  - support more encoding formats of ASN.1
+  - refactor / clean-up (rust) code-generators (most will be removed in v0.3.0)
+  - support more encoding formats of ASN.1 (help is welcome!)
 
 
 #### License

diff --git a/asn1rs-macros/Cargo.toml b/asn1rs-macros/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "asn1rs-macros"
-version = "0.2.0-alpha3"
+version = "0.2.0"
 authors = ["Michael Watzko <[email protected]>"]
 edition = "2018"
 description = "Macros for asn1rs"
@@ -20,6 +20,6 @@ debug-proc-macro = []
 
 
 [dependencies]
-asn1rs-model =  { version = "0.2.0-alpha3", path = "../asn1rs-model" }
+asn1rs-model =  { version = "0.2.0", path = "../asn1rs-model" }
 syn = {version = "1.0.17", features = ["full"] }
 quote = "1.0.3"
diff --git a/asn1rs-model/Cargo.toml b/asn1rs-model/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "asn1rs-model"
-version = "0.2.0-alpha3"
+version = "0.2.0"
 authors = ["Michael Watzko <[email protected]>"]
 edition = "2018"
 description = "Rust, Protobuf and SQL model definitions for asn1rs"