GSoC Final Submission

Contributor: shanmu(@shanmu)
Mentor: Ed Page(@epage)
Project: Move cargo shell completions to Rust
Organization: The Rust Foundation

Overview

The goal of this project can be divided into two phases.

The first phase is related to the clap, where a new command-line completion system (clap_complete) will be built on top of the existing clap. This will allow users to implement multiple shell completions with a single Rust codebase, and it will make it easier for users to extend and add completion results.

The second phase is related to Cargo. Since Cargo's CLI is built using clap, we can use clap_complete to add Rust code for cargo completions. This will make it easier to implement complex completion scripts (e.g., workspace-related or network-related tasks) directly in Rust code. Our goal is to align with the existing hand-written completion scripts.

Before I started this project, there were already some infrastructure had already been established. See feat(complete): Skeleton for Rust-driven completions

Current State of project

At present, we could use rust-native cargo completions easily. See Native-completions to get the new feature and expect your feedback.
Also, user could use clap_complete to add their completion feature for their cli application. See clap_complete::env.

What work has done

What is left to do

What is left to do of the project could be roughly tracked through the following two tracking issues:

In fact, there is still a lot of work to be done—there’s always room for improvement. After GSoC 2024 ends, I will continue to be involved in this project until the release of the stable version.

Others

  • completest
    The completest relies on interactive shells, or more specifically, PTY devices. This approach is quite general, and I believe it would be very meaningful to add support for more shells and platforms, as there are currently many libraries related to shell completion but a lack of end-to-end CI testing (if we added bin target).

What I learned

I think what I've learned can be divided into two parts:how to work with community and some code skills.

How to work with community

  • If we encounter problems, seek help from the community rather than trying to solve them on our own by looking through the source code and search engines. This is also the fastest way to integrate into the community, starting with discussions on issues.
  • Project management is important. Discuss our solutions under issues, discuss the specific code implementation in PRs, and after a PR is merged, provide feedback on the issue updates (such as a tracking comment or closing the issue), ensuring the progress of the project is always traceable. A tracking issue is also very important. It forces us to review all potential problems. When we need to implement a major feature, creating a tracking issue is absolutely necessary.
  • In Rust, documentation is also important because it is user-facing. We can't expect others to have to check our repository (whether it's code or issues) when using new features. We should aim to make the documentation simple and easy to understand, with clear and easy-to-understand examples.

Code skills

  • Be proficient in using combinators, but avoid overusing them to ensure the code remains easy to read and review.
  • Flatten code using if let and match with the ? operator, making it easier to handle errors and perform code reviews.
  • cargo_test made me realize that the test macro can actually be extended, which might give me ideas for adding tests to low-level code in the future.

Acknowledgement

I am extremely grateful to my mentor for providing me with so much help, both in guiding the project from a broader perspective and reviewing the details of my code, as well as being patient with my poor English. I also want to sincerely thank the Rust Foundation and the other GSoC contributors, from whom I have learned a lot.