Rework Charon CLI
Introduction
Charon is a powerful tool for extracting and analyzing Rust code. However, its command-line interface (CLI) can be overwhelming for new users. In this article, we will explore the current state of the Charon CLI and propose a reworked version that is more intuitive and user-friendly.
Current Charon CLI
The current Charon CLI is a complex and dense list of options. While it provides a high degree of flexibility, it can be challenging for users to navigate and understand.
charon\charon $ target\debug\charon --help
Usage: charon [OPTIONS]
Options:
--ullbc
Extract the unstructured LLBC (i.e., don't reconstruct the control-flow)
--lib
Compile the package's library
--bin <BIN>
Compile the specified binary
--mir_promoted
Extract the promoted MIR instead of the built MIR
--mir_optimized
Extract the optimized MIR instead of the built MIR
--crate <CRATE_NAME>
Provide a custom name for the compiled crate (ignore the name computed by Cargo)
--input <INPUT_FILE>
The input file (the entry point of the crate to extract). This is needed if you want to define a custom entry point (to only extract
part of a crate for instance)
--read-llbc <READ_LLBC>
Read an llbc file and pretty-print it. This is a terrible API, we should use subcommands
--dest <DEST_DIR>
The destination directory. Files will be generated as `<dest_dir>/<crate_name>.{u}llbc`, unless `dest_file` is set. `dest_dir` defau
lts to the current directory
--dest-file <DEST_FILE>
The destination file. By default `<dest_dir>/<crate_name>.llbc`. If this is set we ignore `dest_dir`
--polonius
If activated, use Polonius' non-lexical lifetimes (NLL) analysis. Otherwise, use the standard borrow checker
--skip-borrowck
If activated, this skips borrow-checking of the crate
--no-code-duplication
Check that no code duplication happens during control-flow reconstruction
of the MIR code.
This is only used to make sure the reconstructed code is of good quality.
For instance, if we have the following CFG in MIR:
```
b0: switch x [true -> goto b1; false -> goto b2]
b1: y := 0; goto b3
b2: y := 1; goto b3
b3: return y
```
We want to reconstruct the control-flow as:
```
if x then { y := 0; } else { y := 1 };
return y;
```
But if we don't do this reconstruction correctly, we might duplicate
the code starting at b3:
```
if x then { y := 0; return y; } else { y := 1; return y; }
```
When activating this flag, we check that no such things happen.
Also note that it is sometimes not possible to prevent code duplication,
if the original Rust looks like this for instance:
```
match x with
| E1(y,_) | E2(_,y) => { ... } // Some branches are "fused"
| E3 => { ... }
```
The reason is that assignments are introduced when desugaring the pattern
matching, and those assignments are specific to the variant on which we pattern
match (the `E1` branch performs: `y := (x as E1).0`, while the `E2` branch
performs: `y := (x as E2).1`). Producing a better reconstruction is non-trivial.
--extract-opaque-bodies
Usually we skip the bodies of foreign methods and structs with private fields. When this flag is on, we don't
--translate-all-methods
Usually we skip the provided methods that aren't used. When this flag is on, we translate them all
--include <INCLUDE>
Whitelist of items to translate. These use the name-matcher syntax (note: this differs
a bit from the ocaml NameMatcher).
Note: This is very rough at the moment. E.g. this parses `u64` as a path instead of the
built-in type. It is also not possible to filter a trait impl (this will only filter
its methods). Please report bugs or missing features.
Examples:
- `crate::module1::module2::item`: refers to this item and all its subitems (e.g.
submodules or trait methods);
- `crate::module1::module2::item::_`: refers only to the subitems of this item;
- `core::convert::{impl core::convert::Into<_> for _}`: retrieve the body of this
very useful impl;
the most precise pattern wins. E.g.: `charon --opaque crate::module --include
crate::module::_` makes the `module` opaque (we won't explore its contents), but the
items in it transparent (we will translate them if we encounter them.)
--opaque <OPAQUE>
Blacklist of items to keep opaque. Works just like `--include`, see the doc there.
--exclude <EXCLUDE>
Blacklist of items to not translate at all. Works just like `--include`, see the doc there.
--remove-associated-types <REMOVE_ASSOCIATED_TYPES>
List of traits for which we transform associated types to type parameters. The syntax is like `--include`, see the doc there.
--hide-marker-traits
Whether to hide the `Sized`, `Sync`, `Send` and `Unpin` marker traits anywhere they show up
--no-cargo
Do not run cargo; instead, run the driver directly
--rustc-flag <RUSTC_ARGS>
Extra flags to pass to rustc
--cargo-arg <CARGO_ARGS>
Extra flags to pass to cargo. Incompatible with `--no-cargo`
--abort-on-error
Panic on the first error. This is useful for debugging
--error-on-warnings
Consider any warnings as errors
--no-serialize
Don't serialize the final (U)LLBC to a file.
--print-original-ullbc
Print the ULLBC immediately after extraction from MIR.
--print-ullbc
Print the ULLBC after applying the micro-passes (before serialization/control-flow reconstruction).
--print-built-llbc
Print the LLBC just after we built it (i.e., immediately after loop reconstruction).
--print-llbc
Print the final LLBC (after all the cleaning micro-passes).
--no-merge-goto-chains
Do not merge the chains of gotos in the ULLBC control-flow graph.
-h, --help
Print help
Reworking the Charon CLI
To improve the user experience, we propose the following changes to the Charon CLI:
- Simplify the Options: Group related options together and provide clear descriptions for each option.
- Use Subcommands: Introduce subcommands to simplify the CLI and make it easier to use.
- Improve Help Messages: Provide detailed help messages for each option and subcommand.
- Add Examples: Include examples for each option and subcommand to help users understand how to use them.
Proposed CLI Structure
Here is a proposed structure for the reworked Charon CLI:
charon <subcommand> [options]
Subcommands
extract: Extract the unstructured LLBC from the input file.- Options:
--input <INPUT_FILE>: The input file to extract from.--dest <DEST_DIR>: The destination directory for the extracted LLBC.--dest-file <DEST_FILE>: The destination file for the extracted LLBC.--polonius: Use Polonius' non-lexical lifetimes (NLL) analysis.--skip-borrowck: Skip borrow-checking of the crate.--no-code-duplication: Check for code duplication during control-flow reconstruction.
- Options:
compile: Compile the package's library or binary.- Options:
--lib: Compile the package's library.--bin <BIN>: Compile the specified binary.--crate <CRATE_NAME>: Provide a custom name for the compiled crate.--rustc-flag <RUSTC_ARGS>: Extra flags to pass to rustc.--cargo-arg <CARGO_ARGS>: Extra flags to pass to cargo.
- Options:
analyze: Analyze the extracted LLBC.- Options:
--print-original-ullbc: Print the ULLBC immediately after extraction from MIR.--print-ullbc: Print the ULLBC after applying the micro-passes.--print-built-llbc: Print the LLBC just after we built
Charon CLI Rework: Frequently Asked Questions =====================================================
- Options:
Q: What is the purpose of reworking the Charon CLI?
A: The primary goal of reworking the Charon CLI is to improve the user experience by making it more intuitive and user-friendly. This will enable users to easily navigate and understand the various options and subcommands available in Charon.
Q: What changes are being proposed for the Charon CLI?
A: The proposed changes include:
- Simplifying the options by grouping related options together and providing clear descriptions for each option.
- Introducing subcommands to simplify the CLI and make it easier to use.
- Improving help messages for each option and subcommand.
- Adding examples for each option and subcommand to help users understand how to use them.
Q: What are the benefits of using subcommands in the Charon CLI?
A: Using subcommands in the Charon CLI provides several benefits, including:
- Simplified navigation: Subcommands help to organize the CLI and make it easier for users to find the options they need.
- Improved clarity: Subcommands provide a clear and concise way to express complex commands, making it easier for users to understand what they need to do.
- Reduced complexity: Subcommands help to reduce the complexity of the CLI by breaking down complex commands into smaller, more manageable parts.
Q: How will the proposed changes affect existing users of Charon?
A: The proposed changes will not affect existing users of Charon in a significant way. The new CLI structure and subcommands will be designed to be backward compatible, ensuring that existing users can continue to use Charon without any issues.
Q: What is the timeline for implementing the proposed changes?
A: The timeline for implementing the proposed changes will depend on the complexity of the changes and the resources available. However, we anticipate that the changes will be implemented in the following phases:
- Research and planning: 2-4 weeks
- Design and prototyping: 4-6 weeks
- Implementation: 8-12 weeks
- Testing and validation: 4-6 weeks
- Deployment: 2-4 weeks
Q: How will users be notified about the changes to the Charon CLI?
A: Users will be notified about the changes to the Charon CLI through various channels, including:
- Email notifications: Users will receive email notifications about the changes and how to use the new CLI.
- Documentation updates: The Charon documentation will be updated to reflect the changes to the CLI.
- Release notes: Release notes will be provided for each new version of Charon, highlighting the changes and improvements made.
- Community announcements: The Charon community will be notified about the changes through social media and other channels.
Q: What support will be available for users who need help with the new CLI?
A: Users who need help with the new CLI will have access to various support channels, including:
- Documentation: The Charon documentation will be updated to reflect the changes to the CLI.
- Community forums: The Charon community forums will be available for users to ask questions and get help from other users and developers.
- Email support: Users will be able to contact the Charon development team directly for help and support.
- Online resources: Online resources, such as tutorials and videos, will be available to help users learn how to use the new CLI.