Merge branch 'master' into range-checks

Cargo.toml

@@ -22,4 +22,4 @@ nom = "7.1.1"
 pathdiff = "0.2.1"
 which = { version = "4.4.0", optional = true, default-features = false }
 syn = "2.0.16"
-quote = "1.0.26"
+quote = "1.0.31"

docs/docs/command_line_flags.mdx

@@ -149,7 +149,7 @@ cddl-codegen --input=example --output=export --common-import-override=cml_core
 
 <br/><br/>
 
-:::info `--package-json`
+:::info `--wasm-cbor-json-api-macro`
 If it is passed in, it will call the supplied externally defined macro on each exported type, instead of manually exporting the functions for to/from CBOR bytes + to/from JSON API.
 
 The external macro is assumed to exist at the specified path and will be imported if there are module prefixes.

docs/docs/comment_dsl.mdx

@@ -98,7 +98,7 @@ This can also be useful when you have a spec that is either very awkward to use
 This can also be useful when you have a spec that is either very awkward to use (so you hand-write or hand-modify after generation) in some type so you don't generate those types and instead manually merge those hand-written/hand-modified structs back in to the code afterwards. This saves you from having to manually remove all code that is generated regarding `Foo` first before merging in your own.
 
 
-#### _CDDL_CODEGEN_RAW_BYTES_TYPE_
+## _CDDL_CODEGEN_RAW_BYTES_TYPE_
 
 Allows encoding as `bytes` but imposing hand-written constraints defined elsewhere.
 ```cddl

docs/docs/integration-other.mdx

@@ -0,0 +1,32 @@
+---
+sidebar_position: 7
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+# Integration with other cddl-codegen libraries
+
+This guide is written in general for integrating with other libraries generated by cddl-codegen, but in particular references CML (cardano-multiplatform-lib) for examples. Most things referencing CML will be relevant to other common cddl-codegen generated libraries used as dependencies.
+
+## Common cddl-codegen traits
+
+When generating a library that has as a dependency another cddl-codegen-generated library you can share the common cddl-codegen types/traits like `Deserialize`, `RawBytesEncoding`, etc. Remember to pass in `--common-import-override` tag. For CML we pass in `--common-import-override=cml_core`. This is where all the common cddl-codegen traits are located so we can avoid having duplicate incompatible traits in other libraries.
+
+## CML macros
+
+In CML we have macros for implementing WASM conversions and JSON/bytes. We pass in `--wasm-cbor-json-api-macro=cml_core_wasm::impl_wasm_cbor_json_api` and `--wasm-conversions-macro=cml_core_wasm::impl_wasm_conversions` which are both located in `cml_core_wasm`. This drastically reduces WASM wrapper boilerplate.
+
+## Externally defined types
+
+### `_CDDL_CODEGEN_EXTERN_TYPE_` vs `_CDDL_CODEGEN_RAW_BYTES_TYPE_`
+
+There are two ways to have explicitly externally-defined types in cddl-codegen: `_CDDL_CODEGEN_EXTERN_TYPE_` and `_CDDL_CODEGEN_RAW_BYTES_TYPE_`. It is important to choose the appropriate one. If the type was defined originally as `_CDDL_CODEGEN_RAW_BYTES_TYPE_` in CML (or whatever library) then it is important to define it using this so it will be encoded correctly. If the type was either defined using `_CDDL_CODEGEN_EXTERN_TYPE_` (hand-written) or was explicitly defined normally in the dependency lib (e.g. CML) then use `_CDDL_CODEGEN_EXTERN_TYPE_`.
+
+### Import pathing
+
+In order to make imports easier it's recommended to make a directory corresponding to the dependency and put the `_CDDL_CODEGEN_RAW_BYTES_TYPE_` and `_CDDL_CODEGEN_EXTERN_TYPE_` external types inside of there and then later delete the output directories containing those modules. For an example see the `cml_chain` directory inside of the [`specs/multiera`](https://github.com/dcSpark/cardano-multiplatform-lib/tree/develop/specs/multiera).
+
+### Non-black-box types
+
+Another important detail, demonstrated in the above `multiera` CDDL spec, is that when using external types that aren't 100% self-contained (i.e. can't be treated as a black box that implements `Serialize` + `Deserialize`, nor as CBOR bytes implementing `RawBytesEncoding`) like `uint` aliases should be explicitly defined and then removed afterwards. Using the above directory/pathing tip makes this trivial to remove after.

src/cli.rs

@@ -67,13 +67,8 @@ pub struct Cli {
     /// Location override for default common types (error, serialization, etc)
     /// This is useful for integrating into an exisitng project that is based on
     /// these types.
-    #[clap(
-        long,
-        value_parser,
-        value_name = "COMMON_IMPORT_OVERRIDE",
-        default_value = "crate"
-    )]
-    pub common_import_override: String,
+    #[clap(long, value_parser, value_name = "COMMON_IMPORT_OVERRIDE")]
+    common_import_override: Option<String>,
 
     /// An external macro to be called instead of manually emitting functions for
     /// conversions to/from CBOR bytes or JSON.
@@ -97,4 +92,19 @@ impl Cli {
     pub fn lib_name_code(&self) -> String {
         self.lib_name.replace('-', "_")
     }
+
+    /// If someone override the common imports, we don't want to export them
+    pub fn export_static_files(&self) -> bool {
+        self.common_import_override.is_none()
+    }
+
+    pub fn common_import_rust(&self) -> &str {
+        self.common_import_override.as_deref().unwrap_or("crate")
+    }
+
+    pub fn common_import_wasm(&self) -> String {
+        self.common_import_override
+            .clone()
+            .unwrap_or_else(|| self.lib_name_code())
+    }
 }