diff --git a/README.md b/README.md index 327d0976..3e81fec8 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,12 @@ # Typeshare -| Crate | Status | -|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Crate | Status | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | typeshare | [![crates.io version](https://img.shields.io/crates/v/typeshare.svg)](https://crates.io/crates/typeshare) [![crate documentation](https://docs.rs/typeshare/badge.svg)](https://docs.rs/typeshare) ![MSRV](https://img.shields.io/badge/rustc-stable-blue.svg) [![crates.io downloads](https://img.shields.io/crates/d/typeshare.svg)](https://crates.io/crates/typeshare) | | typeshare-core | [![crates.io version](https://img.shields.io/crates/v/typeshare-core.svg)](https://crates.io/crates/typeshare-core) [![crate documentation](https://docs.rs/typeshare-core/badge.svg)](https://docs.rs/typeshare-core) ![MSRV](https://img.shields.io/badge/rustc-stable-blue.svg) [![crates.io downloads](https://img.shields.io/crates/d/typeshare-core.svg)](https://crates.io/crates/typeshare-core) | | typeshare-annotation | [![crates.io version](https://img.shields.io/crates/v/typeshare-annotation.svg)](https://crates.io/crates/typeshare-annotation) [![crate documentation](https://docs.rs/typeshare-annotation/badge.svg)](https://docs.rs/typeshare-annotation) ![MSRV](https://img.shields.io/badge/rustc-stable-blue.svg) [![crates.io downloads](https://img.shields.io/crates/d/typeshare-annotation.svg)](https://crates.io/crates/typeshare-annotation) | | typeshare-cli | [![crates.io version](https://img.shields.io/crates/v/typeshare-cli.svg)](https://crates.io/crates/typeshare-cli) ![MSRV](https://img.shields.io/badge/rustc-stable-blue.svg) [![crates.io downloads](https://img.shields.io/crates/d/typeshare-cli.svg)](https://crates.io/crates/typeshare-cli) | - _One tool to rule the types,_ _One tool to FFI them,_ @@ -16,22 +15,19 @@ _One tool to parse your Rust,_ _And in the darkness, compile them_ πŸ’ +Do you like manually managing types that need to be passed through an FFI layer, so that your code doesn't archaically break at runtime? Be honest, nobody does. Typeshare is here to take that burden away from you! Leveraging the power of the `serde` library, Typeshare is a tool that converts your Rust types into their equivalent forms in Swift, Kotlin, Typescript, and a growing family of other language implementations, keeping your cross-language codebase in sync. With automatic implementation for serialization and deserialization on both sides of the FFI, Typeshare does all the heavy lifting for you. It can even handle generics and convert effortlessly between standard libraries in different languages! -Do you like manually managing types that need to be passed through an FFI layer, so that your code doesn't archaically break at runtime? Be honest, nobody does. Typeshare is here to take that burden away from you! Leveraging the power of the `serde` library, Typeshare is a tool that converts your -Rust types into their equivalent forms in Swift, Go**, Python**, Kotlin, Scala and Typescript, keeping -your cross-language codebase in sync. With automatic implementation for serialization and deserialization on both sides of the FFI, Typeshare does all the heavy lifting for you. It can even handle generics and convert effortlessly between standard libraries in different languages! - -**A few caveats. See [here](#a-quick-refresher-on-supported-languages) for more details. +\*\*A few caveats. See [here](#what-about-other-languages) for more details. ## Installation - To install the CLI (Command Line Interface): + ``` -cargo install typeshare-cli +cargo install typeshare2-cli ``` -πŸ’‘Note that the console command will be `typeshare`, not `typeshare-cli`. +πŸ’‘Note that the console command will be `typeshare2`, not `typeshare2-cli`. In your `Cargo.toml`, under `[dependencies]`: @@ -40,16 +36,17 @@ typeshare = "1.0.0" ``` ## Using Typeshare + We've put together a book that documents (almost) everything you can do. πŸ“š[Read the Typeshare book here!](https://1password.github.io/typeshare) -To generate FFI definitions for a target language, run the `typeshare` command and specify the directory containing your rust code, the language you would like to generate for, and the file to which your generated definitions will be written: +To generate FFI definitions for a target language, run the `typeshare2` command and specify the directory containing your rust code, the language you would like to generate for, and the file to which your generated definitions will be written: + ``` -typeshare ./my_rust_project --lang=kotlin --output-file=my_kotlin_definitions.kt -typeshare ./my_rust_project --lang=swift --output-file=my_swift_definitions.swift -typeshare ./my_rust_project --lang=scala --output-file=my_scala_definitions.scala -typeshare ./my_rust_project --lang=typescript --output-file=my_typescript_definitions.ts +typeshare2 ./my_rust_project --lang=kotlin --output-file=my_kotlin_definitions.kt +typeshare2 ./my_rust_project --lang=swift --output-file=my_swift_definitions.swift +typeshare2 ./my_rust_project --lang=typescript --output-file=my_typescript_definitions.ts ``` ### Annotating Types @@ -73,6 +70,7 @@ enum MyEnum { MyNumber(u32), } ``` + ```typescript // Generated Typescript definitions @@ -82,30 +80,24 @@ export interface MyStruct { } export type MyEnum = - | { type: "MyVariant", content: boolean } - | { type: "MyOtherVariant", content: undefined } - | { type: "MyNumber", content: number }; + | { type: "MyVariant"; content: boolean; } + | { type: "MyOtherVariant"; content: undefined; } + | { type: "MyNumber"; content: number; }; ``` ## Getting Help Are you getting weird deserialization issues? Did our procedural macro throw a confusing error at you? Are you trying to contribute and our existing codebase is confusing? (probably true) Did you have another problem not enumerated in this reductive list? Please open an issue in this repository and the 1Password team would be happy to help! That's what we're here for! -## A Quick Refresher on Supported Languages +## What about other languages? -- Kotlin -- Scala -- Swift -- Typescript -- Go** -- Python** (see list of limitations [here](https://github.com/1Password/typeshare/issues/217)) +The official `typeshare2` binary supports Swift, Kotlin, and Typescript, but there are unofficial implementations out there for other languages. Feel free to add your own to this list (check out the [app](./app/README.md) directory for details on how to create your own typeshare). +- [typeshare-java](https://crates.io/crates/typeshare-java) -If there is a language that you want Typeshare to generate definitions for, you can either: -1. Open an issue in this repository requesting your language of choice. -2. Implement support for that language and open a PR with your implementation. We would be eternally grateful! πŸ™ +### The language I want isn't supported -** Right now, Go and Python support is experimental. Enable the `go` or `python` features, respectively, when installing typeshare-cli if you want to use these. +Typeshare is designed to make it as easy as possible to implement your own languages. Take a look at the [app](./app/README.md) directory for details on how to get started. ## Credits diff --git a/app/driver/README.md b/app/driver/README.md index 36c52c78..312d9ab0 100644 --- a/app/driver/README.md +++ b/app/driver/README.md @@ -12,4 +12,4 @@ use typeshare_python::Python; typeshare_binary! { Python, Golang } ``` -This creates an `fn main` that uses these languages, plus `typeshare-engine`, to implements a full typeshare CLI. +This creates a `fn main` that uses these languages, plus `typeshare-engine`, to implement a full typeshare CLI. diff --git a/app/engine/README.md b/app/engine/README.md index fc8f0a53..528ea21d 100644 --- a/app/engine/README.md +++ b/app/engine/README.md @@ -1,5 +1,5 @@ # typeshare-engine -This crate includes all of the actual implementations of typeshare functionality. It should be a dependency of anyone trying to USE typeshare as a library. It depends ONLY on typeshare-model, not on any language crates. It exports functions that make use of the trait in typeshare-model. +This crate includes all of the actual implementations of typeshare functionality. It should be a dependency of anyone trying to USE typeshare as a library. It exports functions that make use of the trait in typeshare-model. -Currently, the public API of typeshare-engine is considered fairly unstable. Feel free to use it, but we expect updates to usually be published as major versions. You only need to depend on `typeshare-engine` if you want to use typeshare as a _library_; if you're implementing your own language, you only need to depend on `typeshare-model`, and if you're creating a typeshare binary, you only also need `typeshare-driver`. +Currently, the public API of typeshare-engine is considered fairly unstable. Feel free to use it, but we expect updates to usually be published as major versions. You only need to depend on `typeshare-engine` if you want to use typeshare as a _library_; if you're implementing your own language, you only need to depend on [typeshare-model](../model), and if you're creating a typeshare binary, you only also need [typeshare-driver](../driver) diff --git a/app/model/README.md b/app/model/README.md index f648f203..b29b5e8f 100644 --- a/app/model/README.md +++ b/app/model/README.md @@ -1,3 +1,3 @@ # typeshare-model -This crate is the base dependency for almost everything else. It includes especially the types and traits necessary for a single language implementation (that is, typeshare-swift could depend ONLY on typeshare-model). It can include utility functionality that might be necessary for a language implementation, but ideally not much in the way of major implementation stuff. +This crate is the core dependency for all implementations of specific languages for typeshare. It defines the [`Language`](https://docs.rs/typeshare-model/latest/typeshare_model/trait.Language.html) trait, along with a handful of supporting types, which a language implementation must implement. Check out the official implementations for [Swift](../langs/swift/src/lib.rs), [Kotlin](../langs/kotlin/src/lib.rs), and [Typescript](../langs/typescript/src/lib.rs) for examples. diff --git a/app/model/src/language.rs b/app/model/src/language.rs index b1038adf..6d06d84a 100644 --- a/app/model/src/language.rs +++ b/app/model/src/language.rs @@ -128,7 +128,7 @@ language to emit appropriate import statements for its own language. language.write_imports(&mut file, crate_name, computed_imports) ``` -6. For EACE typeshared item in being typeshared, we call `write_enum`, +6. For EACH typeshared item in being typeshared, we call `write_enum`, `write_struct`, `write_type_alias`, or `write_const`, as appropriate. ```ignore @@ -181,7 +181,7 @@ pub trait Language<'config>: Sized + Sync + Debug { `serde`. It is important that this type include `#[serde(default)]` or something - equivelent, so that a config can be loaded with default setting even + equivalent, so that a config can be loaded with default setting even if this language isn't present in the config file. The `serialize` implementation for this type should NOT skip keys, if diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 2c7ea4b6..04cabc4d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,8 +2,10 @@ - [Overview](./overview.md) - [Installation](./installation.md) +- [Language Implementation](./new-languages.md) +- [Testing your Typeshare](./testing.md) - [Usage](./usage/usage.md) - - [Annotations](./usage/annotations.md) - - [Configuration](./usage/configuration.md) - - [Target OS](./usage/target_os.md) + - [Annotations](./usage/annotations.md) + - [Configuration](./usage/configuration.md) + - [Target OS](./usage/target_os.md) - [Contributing](./contributing.md) diff --git a/docs/src/contributing.md b/docs/src/contributing.md index 395fc31a..752f09d1 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -2,6 +2,8 @@ Thank you! If you would like to contribute to the project, go to [the GitHub repository](https://github.com/1Password/typeshare). There, you can open issues to report bugs and request features. +If you want to implement your own language, you can do so as a separate crate! Check out the walkthrough [here](./new-languages.md). + If you want to contribute code, please send a [GitHub Pull Request](https://github.com/1Password/typeshare/pull/new/master) to the repository with a clear list of your changes and the reasons for the changes. Before contributing, you should probably familiarize yourself with the internal documentation, if you haven't already. Make sure to look through the READMEs for each part of Typeshare you plan to contribute to, and double-check the Rust documentation on `docs.rs` if you want to know more about the API. And feel free to open an issue if you want to ask the 1Password team directly, or if the documentation is unclear. For larger changes, please open an RFC issue first in order to discuss the broader impacts of the proposed change with the other maintainers. \ No newline at end of file diff --git a/docs/src/installation.md b/docs/src/installation.md index 605b6a90..4d073802 100644 --- a/docs/src/installation.md +++ b/docs/src/installation.md @@ -1,10 +1,15 @@ # Installation -The easiest way to install the Typeshare CLI is with `cargo`. Just run the following command: +Identify which typeshare implements the language(s) you'd like to use, and install it with `cargo install`. The official typeshare binary supports Kotlin, Swift, and Typescript: + ``` -cargo install typeshare-cli +cargo install typeshare2-cli ``` +There are also third party crates implementing other languages using typeshare, such as: + +- Java: `cargo install typeshare-java` + Once you have the CLI installed, you then need to annotate the rust types that you want to generate FFI definitions for. In order to be able to use the `#[typeshare]` annotation, you will need to add `typeshare` as a dependency to your project's `Cargo.toml`. ```toml diff --git a/docs/src/new-languages.md b/docs/src/new-languages.md new file mode 100644 index 00000000..13db5e31 --- /dev/null +++ b/docs/src/new-languages.md @@ -0,0 +1,115 @@ +# Making your own typeshare + +Typeshare is designed to make it easy to implement your own languages as a separate binary. This document provides a basic walkthrough for how to create your own langauge implementation. + +## Project Structure + +There are two key components to making your own Typeshare implementation: +- `typeshare-model` +- `typeshare-driver` + +In a typical Typeshare project, each language implementation will be its own crate, with the `typeshare-driver` bringing your implementations together into a single CLI binary. + +``` +typeshare-binary +β”œβ”€β”€ typeshare-language-1 +β”‚ β”œβ”€β”€ src +β”‚ β”‚ └── lib.rs +β”‚ └── cargo.toml +β”œβ”€β”€ typeshare-language-2 +β”‚ β”œβ”€β”€ src +β”‚ β”‚ └── lib.rs +β”‚ └── cargo.toml +β”œβ”€β”€ src +β”‚ └── main.rs +└── cargo.toml +``` + +## Start the Project + +Set up the binary: + +```bash +cargo new my-typeshare-binary +cd my-typeshare-binary +``` + +This is where the `typeshare-driver`'s main macro for setting up the binary will be. Add the `typeshare-driver` dependency +```bash +cargo add typeshare-driver +``` +You will also need to add the dependency `log` + +```bash +cargo add log +``` + +Add a crate for your language implementation (or as many as you want! Up to 16): +```bash +cargo new my-typeshare-language --lib +cd my-typeshare-language +``` +Once you have your language crate, add the `typeshare-model` dependency: + +```bash +cargo add typeshare-model +``` +Some other dependencies you will need to implement your own language include: +- `thiserror` +- `serde` with the feature `derive` +- `joinery` +- `itertools` +- `anyhow` + +So make sure to add these to your language crate as well + +## Implementing a Language + +Once your project is set up, you need to implement the Language trait from `typeshare-model` inside your langugae crate. + +There a few functions that have to be implemented: +- `new_from_config`: This instantiates your language struct using configuration from a `typeshare.toml` file or the command line +- `output_filename_for_crate`: This is used in multi-file mode for setting up consistent naming for the files. +- `write_*`: These functions are your implementations of how various types should be handled. These implementations should typically call `format_type`, which is used to format Rust types into strings for writing to the Typeshare generated file. +- `format_special_type`: This is where you add custom implementations of special types for each language that is called from within `format_type`. + +Additional functions that are optional but common to implement include: +- `mapped_type`: This allows you to create specific custom handling for specific types. +- `begin_file`, `end_file`, `write_additional_files` to add other per-file or per-directory handling, such as information about the file generation in comments at the top of the file, or other custom handling. + +See the function documentation for more detailed information and look through our implementations of Typeshare for [Kotlin](../../app/langs/kotlin/), [Swift](../../app/langs/swift/), and [Typescript](../../app/langs/typescript/) for examples. + +Once the Language trait has been implemented, your Typeshare is ready to be built! + +## Building Your Typeshare + +In `main.rs` once your language has been implemented, all you have to do is pass them into the `typeshare_driver` macro: +```rust +use typeshare_driver::typeshare_binary; +use typeshare_language_1::YourLanguage1; +use typeshare_language_2::YourLanguage2; + +typeshare_binary! { YourLanguage1, YourLanguage2 } +``` +Now, running `cargo build` will build your Typeshare with your language implementations and create a fully functional CLI tool. + +## Using Your Typeshare + +In a project where you want to use Typeshare, add `typeshare` to your `cargo.toml` and add the Typeshare annotations to any types you want to share (see more about using annotations [here](./usage/annotations.md)). Set up a `typeshare.toml` at the root of your project with any configuration information for your implementation. + +The general usage of a Typeshare CLI binary is: +```bash +typeshare-binary --lang --output-file +``` +or +```bash +typeshare-binary --lang --output-folder +``` +depending if you want the generated code to be outputted into a folder or a file. + +To run your Typeshare for multiple languages, you rerun the command with each desired language. + +To see all possible languages in a Typeshare and learn about other possible commands run: +```bash +typeshare-binary --help +``` \ No newline at end of file diff --git a/docs/src/overview.md b/docs/src/overview.md index 102bee04..f8383788 100644 --- a/docs/src/overview.md +++ b/docs/src/overview.md @@ -2,6 +2,6 @@ Typeshare is a tool for generating type definitions in other languages based on type definitions in Rust. Specifically, Typeshare is useful for FFI where types are passed as fully serialized blobs, and then decoded on the other side. -Typeshare was originally developed as an internal tool at [1Password](1password.com), but has been released as an open-source crate that you can use and contribute to. +Typeshare was originally developed as an internal tool at [1Password](1password.com), but has been released as an open-source crate that you can use to implement your own Typeshare for any language. -This guide describes how to install and use Typeshare effectively. \ No newline at end of file +This guide describes how to install and use Typeshare effectively and how to implement your own Typeshare. diff --git a/docs/src/testing.md b/docs/src/testing.md new file mode 100644 index 00000000..0383fb3c --- /dev/null +++ b/docs/src/testing.md @@ -0,0 +1,92 @@ +# Testing Your Typeshare + +## Setting up Snapshot Testing for Typeshare + +When you have a working Typeshare, you likely will want some way to validate that making changes to the implementation: +1. Does what you expect it to do and +2. Doesn't alter previously expected behaviour + +The way this is achieved in Typeshare is with snapshot testing. The `typeshare-snapshot-test` tool enables you to generate snapshots from your Typeshare's current state of type generation and test future changes against these snapshots. To install the CLI run: +```bash +cargo install typeshare-snapshot-test +``` +This will install the tool globally. You can learn more about the crate [here](https://crates.io/crates/typeshare-snapshot-test) + +## Generating Snapshots + +To generate snapshot tests, first you need to set up your file structure. To set up your snapshot tests, make a directory where they will all be stored. + +Inside this directory, every subdirectory is a test. Tests can be structured with one or more rust input files. They can also be set up to support multi-file mode. Each test can be set up with its own config `typeshare.toml` file for test-specific configuration. +``` +snapshot-tests +β”œβ”€β”€ test-1 +β”‚ β”œβ”€β”€ input.rs +β”‚ └── typeshare.toml +β”œβ”€β”€ test-2 +β”‚ β”œβ”€β”€ input-1.rs +β”‚ β”œβ”€β”€ input-2.rs +β”‚ └── typeshare.toml +└── multi-file-test + └── input + β”œβ”€β”€ basic_crate + β”‚ └── src + β”‚ └── lib.rs + └── dependent_crate + └── src + └── lib.rs +``` +To generate snapshots, `typeshare-snapshot-test` will generate snapshots from this directory structure, outputing either an output file or a folder with the language's name if it is a multi-file test. + +The basic command to geenrate snapshots is + +```bash +typeshare-snapshot-test --typeshare --language --suffix --mode generate +``` + +To generate snapshots for multiple languages in your Typeshare, rerun the generation command for each language. + + +## Testing Against Snapshots + +To run the snapshot tests, pass in `test` to the `--mode` flag instead of `generate`. + +```bash +typeshare-snapshot-test --typeshare --language --suffix --mode test +``` + +This will run all the tests for the specified language. To run any snaphshot tests for other languages in your Typeshare, rerun the command for each language. + +## Generating and Running Individual Tests + +Sometimes you don't want to run all the tests in the snapshot test directory. `typeshare-snapshot-test` uses the test folders' names as the tests' names. Specific tests can be specified by name with the `--include` flag. Use this flag multiple times to run multiple tests. + +```bash +typeshare-snapshot-test --typeshare --language --suffix --include --include --mode test +``` + +This can also be used to only generate new snapshots for specific tests instead of all the tests within the snapshot-tests directory. + +```bash +typeshare-snapshot-test --typeshare --language --suffix --include --include --mode generate +``` +A common usage of this is if your Typeshare has multiple languages. Some tests might be for specific languages or specific subsets of languages. + +For example: +``` +snapshot-tests +β”œβ”€β”€ test-go-and-ts +β”‚ β”œβ”€β”€ input.rs +β”‚ β”œβ”€β”€ output.ts +β”‚ β”œβ”€β”€ output.go +β”‚ └── typeshare.toml +β”œβ”€β”€ test-1-ts-only +β”‚ β”œβ”€β”€ input.rs +β”‚ β”œβ”€β”€ output.ts +β”‚ └── typeshare.toml +└── test-2-go-only + β”œβ”€β”€ input-1.rs + β”œβ”€β”€ output.go + └── typeshare.toml +``` +Using the include flag lets you create and run any combinations of tests with specific languages. + diff --git a/docs/src/usage/configuration.md b/docs/src/usage/configuration.md index 80fc93d9..0f416e4c 100644 --- a/docs/src/usage/configuration.md +++ b/docs/src/usage/configuration.md @@ -1,42 +1,36 @@ # Configuration -The behaviour of Typeshare can be customized by either passing options on the command line or in a configuration file. For any command line option that corresponds to a value in the configuration file, specifying the option on the command line will override the value in the configuration file. +Your Typeshare can be customized by either passing options on the command line or in a configuration file. The `typeshare-driver` will automatically create command line flags from the Config struct in your language. For any command line option that corresponds to a value in the configuration file, specifying the option on the command line will override the value in the configuration file. -## Command Line Options +Some base commands are available in any Typeshare implementation's CLI + +## Base Command Line Options - `-l`, `--lang` - (Required) The language you want your definitions to be generated in. Currently, this option can be set to either `kotlin`, `swift`, `go`, or `typescript`. + (Required) The language you want your definitions to be generated in. This will be one of the languages supported by the Typeshare you are using. - `-o`, `--output-file` (Required or -d) The file path to which the generated definitions will be written. - `-d`, `--directory` (Required or -o) The folder path to write the multiple module files to. -- `-s`, `--swift-prefix` - Specify a prefix that will be prepended to type names when generating types in Swift. - -- `-M`, `--module-name` - Specify the name of the Kotlin module for generated Kotlin source code. - - `-t`, `--target-os` Optional comma separated list of target os targets. Types that are restricted via `#[cfg(target_os = ]` that do not match the argument list will be filtered out. -- `-j`, `--java-package` - Specify the name of the Java package for generated Kotlin types. - -- `-c`, `--config-file` +- `-c`, `--config`, `--config-file` Instead of searching for a `typeshare.toml` file, this option can be set to specify the path to the configuration file that Typeshare will use. -- `-g`, `--generate-config-file` - Instead of running Typeshare with the provided options, generate a configuration file called `typeshare.toml` containing the options currently specified as well as default configuration parameters. -- `--directories` - A list argument that you can pass any number of glob patterns to. All folders and files given will be searched recursively, and all Rust sources found will be used to create a singular language source file. -- `--go-package` - The name of the Go package for use with building for Go. This will be included in the header of the output file. This option will only be available if `typeshare-cli` was built with the `go` feature. +## Custom Config Command Line Options + +To see what specific flags you can use from your implementation's config implementation, run: +```bash +your-typeshare-binary --help +``` +for a full list of possible flags. ## Configuration File - By default, Typeshare will look for a file called `typeshare.toml` in your current directory or any of its parent directories. Typeshare configuration files will look like this: + By default, Typeshare will look for a file called `typeshare.toml` in your current directory or any of its parent directories. Typeshare configuration files will look like something this: ```toml [swift] prefix = 'MyPrefix' @@ -55,9 +49,4 @@ package = 'com.example.package' "DateTime" = "String" ``` -In the configuration file, you can specify the options you want to set so that they do not need to be specified when running Typeshare from the command line. You can also define custom type mappings to specify the foreign type that a given Rust type will correspond to. - -In order to create a config file you can run the following command to generate one in your current directory. -``` -typeshare -g -``` +In the configuration file, you can specify the options you want to set so that they do not need to be specified when running Typeshare from the command line. These options will correspond to the Config struct for the Typeshare language implementation. diff --git a/docs/src/usage/target_os.md b/docs/src/usage/target_os.md index df36df0d..5bf856ec 100644 --- a/docs/src/usage/target_os.md +++ b/docs/src/usage/target_os.md @@ -63,17 +63,17 @@ The following example will not allow `MyType` to be typeshared. ## Combined with features or other cfg attributes -Typehshare will not take into consideration any other `cfg` attributes other than `target_os` when generating types. +Typeshare will not take into consideration any other `cfg` attributes other than `target_os` when generating types. For example: ```rust -#[cfg(any(target_os = "android", feature = "android-test")] +#[cfg(any(target_os = "android", feature = "android-test"))] pub struct MyType; ``` ```rust -#[cfg(all(target_os = "android", feature = "android-test")] +#[cfg(all(target_os = "android", feature = "android-test"))] pub struct MyType; ``` diff --git a/docs/src/usage/usage.md b/docs/src/usage/usage.md index 9827a7ee..03fae14d 100644 --- a/docs/src/usage/usage.md +++ b/docs/src/usage/usage.md @@ -1,29 +1,27 @@ # Usage -This section will cover how to use Typeshare to generate type definitions for your project and how to interact with them across FFI. +This section will cover how to use Typeshare to generate type definitions for your project and how to interact with them across FFI. -Typeshare provides a CLI tool that will perform the necessary generation for any types you annotate in your Rust code. +A Typeshare binary provides a CLI tool that will perform the necessary generation for any types you annotate in your Rust code. -To generate ffi definitions for a specific target language, run the `typeshare` command and specify the directory containing your rust code, the language you would like to generate for, and the file to which your generated definitions will be written: -``` -typeshare ./my_rust_project --lang=kotlin --output-file=my_kotlin_definitions.kt -typeshare ./my_rust_project --lang=swift --output-file=my_swift_definitions.swift -typeshare ./my_rust_project --lang=typescript --output-file=my_typescript_definitions.ts -typeshare ./my_rust_project --lang=scala --output-file=my_scala_definitions.scala -``` -The first command-line argument is the name of the directory to search for Rust type definitions. The CLI will search all files in the specified directory tree for annotated Rust types. In addition to the input directory, you will also need to specify your desired target language and the output file to which the generated types will be written. This is done with the `--lang` and `--output-file` options respectively. +There are a few options for where to find various Typeshare language implementations. You can implement your own (see [here](../new-languages.md)), use language implementations by other open source developers (eg. [typeshare-java](https://crates.io/crates/typeshare-java)), or use 1Password's Typeshare2 CLI. -The currently supported output languages are: +The currently supported output languages in the 1Password provided Typeshare2 CLI are: - Kotlin - Typescript - Swift -- Scala -- Go ---- -If your favourite language is not in this list, consider opening an issue to request it or try implementing it yourself! See our [contribution guidelines](../contributing.md) for more details. +To generate ffi definitions for a specific target language, run the CLI command for the Typeshare you are using. Specify the directory containing your rust code, the language you would like to generate for, and the file to which your generated definitions will be written. For example, with 1Password's Typeshare CLI: + +``` +typeshare2 ./my_rust_project --lang=kotlin --output-file=my_kotlin_definitions.kt +typeshare2 ./my_rust_project --lang=swift --output-file=my_swift_definitions.swift +typeshare2 ./my_rust_project --lang=typescript --output-file=my_typescript_definitions.ts +``` + +The first command-line argument is the name of the directory to search for Rust type definitions. The CLI will search all files in the specified directory tree for annotated Rust types. In addition to the input directory, you will also need to specify your desired target language and the output file to which the generated types will be written. This is done with the `--lang` and `--output-file` options respectively. --- -In the following sections, we will learn how to customize the behaviour of Typeshare using the provided `#[typeshare]` attribute and configuration options. +If your favourite language is not in this list, try implementing it yourself! See how in our [language implementation guide](../new-languages.md) for more details.