Prepare for v0.1.0 release (#21)

* Add cgp and cgp-extra placeholder crates * Update crate readme * Update Cargo.toml * Update readme
contextgeneric · Sep 2, 2024 · edae1a9 · edae1a9
1 parent c545eb3
commit edae1a9
Show file tree

Hide file tree

Showing 30 changed files with 144 additions and 71 deletions.
diff --git a/.rustfmt.toml b/.rustfmt.toml
@@ -3,9 +3,5 @@ reorder_imports = true
 
 # nightly only
 
-# unstable_features = true
-# format_strings = false
-# comment_width = 100
-# wrap_comments = true
 # group_imports = "StdExternalCrate"
 # imports_granularity = "Module"
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,6 +3,9 @@
 resolver = "2"
 
 members = [
+    "crates/cgp",
+    "crates/cgp-core",
+    "crates/cgp-extra",
     "crates/cgp-async",
     "crates/cgp-async-macro",
     "crates/cgp-sync",
@@ -15,20 +18,21 @@ members = [
     "crates/cgp-error",
     "crates/cgp-error-eyre",
     "crates/cgp-error-std",
-    "crates/cgp-core",
     "crates/cgp-run",
     "crates/cgp-inner",
 ]
 
 [workspace.package]
-rust-version    = "1.75"
+rust-version    = "1.79"
 edition         = "2021"
 license         = "Apache-2.0"
-repository      = "https://github.com/informalsystems/cgp"
+repository      = "https://github.com/contextgeneric/cgp"
 authors         = ["Informal Systems <[email protected]>", "Soares Chen <[email protected]>"]
 
 [patch.crates-io]
+cgp                         = { path = "./crates/cgp" }
 cgp-core                    = { path = "./crates/cgp-core" }
+cgp-extra                   = { path = "./crates/cgp-extra" }
 cgp-async                   = { path = "./crates/cgp-async" }
 cgp-async-macro             = { path = "./crates/cgp-async-macro" }
 cgp-sync                    = { path = "./crates/cgp-sync" }

diff --git a/README.md b/README.md
@@ -1,2 +1,37 @@
 
-# Context-generic programming
+# `cgp` - Context-Generic Programming Libraries in Rust
+
+[![Apache 2.0 Licensed](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](https://github.com/informalsystems/cgp/blob/master/LICENSE)
+![Rust Stable](https://img.shields.io/badge/rustc-stable-blue.svg)
+![Rust 1.79+](https://img.shields.io/badge/rustc-1.79+-blue.svg)
+
+## Overview
+
+The `cgp` project contains a collection of micro Rust crates that empowers 
+_context-generic programming_ (CGP), a new programming paradigm in Rust.
+To learn more about context-generic programming, check out the book
+[Context-Generic Programming Patterns](https://patterns.contextgeneric.dev/).
+
+## Crates Organization
+
+The CGP core constructs are organized as many child crates that are intended
+to be minimal and stable. Having each construct defined in separate crate 
+helps us avoid introducing breaking changes in semantic  versioning, in case 
+an unrelated construct is updated.
+
+We also offers meta-crates that aggregate the dependencies from many CGP
+child crates into one place, so that users can use CGP by specifying only one 
+dependency:
+
+- [`cgp`](./crates/cgp/) - The main crate that includes all child crates defined in this project.
+- [`cgp-core`](./crates/cgp-core) - Meta crate that includes core CGP crates that
+- [`cgp-extra`](./crates/cgp-extra) - Meta crate that includes additional CGP crates that may be non-essential or unstable.
+
+The following library crates are provided:
+
+- [`cgp-component`](./crates/cgp-component) - Defines the core CGP component traits and macros.
+- [`cgp-async`](./crates/cgp-async/) - Defines the `Async` trait as an alias for async-safe types.
+- [`cgp-error`](./crates/cgp-error/) - Defines the `HasErrorType` component and error handling constructs.
+- [`cgp-field`](./crates/cgp-field/) - Defines the `HasField` trait to enable the use of data-generic programming with CGP.
+- [`cgp-inner`](./crates/cgp-inner/) - Defines the `HasInner` component which enables composition-based implementation in CGP.
+- [`cgp-run`](./crates/cgp-run) - Defines the `CanRun` component for implementing async runners.
diff --git a/crates/cgp-async-macro/Cargo.toml b/crates/cgp-async-macro/Cargo.toml
@@ -6,15 +6,11 @@ repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
 version      = "0.1.0"
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core macros
+    Context-generic programming async macros
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [lib]
 proc-macro = true
 

diff --git a/crates/cgp-async-macro/src/lib.rs b/crates/cgp-async-macro/src/lib.rs
@@ -1,10 +1,19 @@
+/*!
+   This library provides helper macros for using async functions in traits.
+*/
+
 extern crate proc_macro;
 
 use proc_macro::TokenStream;
 
 mod impl_async;
 mod strip_async;
 
+/**
+   This macro can be used in place of the [`macro@native_async`] macro
+   to strip away all use of `async` and `.await` syntax. This helps emulate
+   async-generic by turnining async functions into sync functions.
+*/
 #[proc_macro_attribute]
 pub fn strip_async(_attr: TokenStream, stream: TokenStream) -> TokenStream {
     strip_async::strip_async(stream.into()).into()

diff --git a/crates/cgp-async/Cargo.toml b/crates/cgp-async/Cargo.toml
@@ -6,7 +6,6 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
     Async-generic primitives to support both sync/async in Context-generic programming

diff --git a/crates/cgp-component-macro-lib/Cargo.toml b/crates/cgp-component-macro-lib/Cargo.toml
@@ -6,15 +6,11 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core macros
+    Context-generic programming core component macros implemented as a library.
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [dependencies]
 syn = { version = "2.0.37", features = [ "full" ] }
 quote = "1.0.33"

diff --git a/crates/cgp-component-macro-lib/src/lib.rs b/crates/cgp-component-macro-lib/src/lib.rs
@@ -1,3 +1,10 @@
+/*!
+   This is an internal crate used by the `cgp-component-macro` crate. We implement the
+   proc macros for `cgp-component` as a library, so that it can be more easily tested.
+   The constructs are then re-exported as proc macros in the `cgp-component-macro` crate,
+   which is defined as a proc macro crate.
+*/
+
 pub mod delegate_components;
 pub mod derive_component;
 

diff --git a/crates/cgp-component-macro/Cargo.toml b/crates/cgp-component-macro/Cargo.toml
@@ -6,15 +6,11 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core macros
+    Context-generic programming core component macros
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [lib]
 proc-macro = true
 

diff --git a/crates/cgp-component-macro/src/lib.rs b/crates/cgp-component-macro/src/lib.rs
@@ -1,3 +1,7 @@
+/*!
+   This crate provides the proc macros used for defining CGP components.
+*/
+
 extern crate proc_macro;
 
 use proc_macro::TokenStream;

diff --git a/crates/cgp-component/Cargo.toml b/crates/cgp-component/Cargo.toml
@@ -6,15 +6,11 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core traits
+    Context-generic programming core component traits
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [dependencies]
 cgp-async = { version = "0.1.0" }
 cgp-component-macro = { version = "0.1.0" }
diff --git a/crates/cgp-component/src/lib.rs b/crates/cgp-component/src/lib.rs
@@ -1,5 +1,10 @@
 #![no_std]
 
+/*!
+   This crate defines the core CGP traits, [`DelegateComponent`] and [`HasComponents`].
+   It also re-export component macros provided by [`cgp_component_macro`].
+*/
+
 pub mod traits;
 
 pub use cgp_component_macro::{define_components, delegate_components, derive_component};

diff --git a/crates/cgp-core/Cargo.toml b/crates/cgp-core/Cargo.toml
@@ -6,19 +6,14 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
     Context-generic programming core traits
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [dependencies]
 cgp-async       = { version = "0.1.0" }
 cgp-component   = { version = "0.1.0" }
 cgp-error       = { version = "0.1.0" }
 cgp-field       = { version = "0.1.0" }
-cgp-run         = { version = "0.1.0" }
 cgp-inner       = { version = "0.1.0" }
diff --git a/crates/cgp-core/src/lib.rs b/crates/cgp-core/src/lib.rs
@@ -3,7 +3,7 @@
 pub mod prelude;
 
 pub use cgp_async::{async_trait, Async};
-pub use {
-    cgp_component as component, cgp_error as error, cgp_field as field, cgp_inner as inner,
-    cgp_run as run,
-};
+pub use cgp_component as component;
+pub use cgp_error as error;
+pub use cgp_field as field;
+pub use cgp_inner as inner;
diff --git a/crates/cgp-error-eyre/Cargo.toml b/crates/cgp-error-eyre/Cargo.toml
@@ -6,10 +6,9 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core traits
+    Context-generic programming error handlers implemented using eyre
 """
 
 [dependencies]

diff --git a/crates/cgp-error-std/Cargo.toml b/crates/cgp-error-std/Cargo.toml
@@ -6,10 +6,9 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core traits
+    Context-generic programming error handlers implemented using `std::error::Error`
 """
 
 [dependencies]

diff --git a/crates/cgp-error/Cargo.toml b/crates/cgp-error/Cargo.toml
@@ -6,10 +6,9 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core traits
+    Context-generic programming error components
 """
 
 [dependencies]

diff --git a/crates/cgp-extra/Cargo.toml b/crates/cgp-extra/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name         = "cgp-extra"
+version      = "0.1.0"
+edition      = { workspace = true }
+license      = { workspace = true }
+repository   = { workspace = true }
+authors      = { workspace = true }
+rust-version = { workspace = true }
+keywords     = ["context-generic programming"]
+description  = """
+    Context-generic programming extra meta-crate
+"""
+
+[dependencies]
+cgp-run        = { version = "0.1.0" }
diff --git a/crates/cgp-extra/src/lib.rs b/crates/cgp-extra/src/lib.rs
@@ -0,0 +1 @@
+pub use cgp_run as run;
diff --git a/crates/cgp-field-macro-lib/Cargo.toml b/crates/cgp-field-macro-lib/Cargo.toml
@@ -6,15 +6,11 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core macros
+    Context-generic programming field macros as a library
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [dependencies]
 syn = { version = "2.0.37", features = [ "full" ] }
 quote = "1.0.33"

diff --git a/crates/cgp-field-macro-lib/src/lib.rs b/crates/cgp-field-macro-lib/src/lib.rs
@@ -1,3 +1,10 @@
+/*!
+   This is an internal crate used by the `cgp-field-macro` crate. We implement the
+   proc macros for `cgp-field` as a library, so that it can be more easily tested.
+   The constructs are then re-exported as proc macros in the `cgp-field-macro` crate,
+   which is defined as a proc macro crate.
+*/
+
 pub mod field;
 pub mod symbol;
 

diff --git a/crates/cgp-field-macro/Cargo.toml b/crates/cgp-field-macro/Cargo.toml
@@ -6,15 +6,11 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core macros
+    Context-generic programming field macros
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [lib]
 proc-macro = true
 

diff --git a/crates/cgp-field/Cargo.toml b/crates/cgp-field/Cargo.toml
@@ -6,14 +6,10 @@ license      = { workspace = true }
 repository   = { workspace = true }
 authors      = { workspace = true }
 rust-version = { workspace = true }
-readme       = "README.md"
 keywords     = ["context-generic programming"]
 description  = """
-    Context-generic programming core traits
+    Context-generic programming field traits
 """
 
-[package.metadata.docs.rs]
-all-features = true
-
 [dependencies]
 cgp-field-macro = { version = "0.1.0" }