Skip to content

GEMINI.md

Latest commit

 

History

History
153 lines (106 loc) · 4.03 KB

GEMINI.md

File metadata and controls

153 lines (106 loc) · 4.03 KB

Gemini Code Understanding

Project Overview

This project provides idiomatic Rust client libraries for Google Cloud Platform (GCP) services. The goal is to offer a natural and familiar API for Rust developers to interact with GCP. The libraries are under active development, and the APIs are subject to change.

The project is structured as a Rust workspace, containing numerous crates. Most of the client libraries are auto-generated from Protobuf service specifications. The core components include:

  • Generated Libraries: Located in src/generated, these are the auto-generated client libraries for various GCP services.
  • Authentication: The src/auth crate handles authentication with Google Cloud.
  • GAX (Google API Extensions): The src/gax crate provides common components for all clients, including error handling, retry policies, and backoff strategies. src/gax-internal contains implementation details shared across clients.
  • Long-Running Operations (LRO): The src/lro crate provides support for handling long-running operations.
  • Well-Known Types (WKT): The src/wkt crate contains shared types used across the libraries.
  • Cloud Storage: The src/storage crate contains a client library for Google Cloud Storage.

Building and Running

The project uses Cargo, the Rust build tool and package manager.

Building the Project

To build the entire workspace, run the following command from the root directory:

cargo build

Running Tests

To run the tests for the entire workspace, use the following command:

cargo test

To run the linter for a particular crate, use the following command:

cargo test -p ${crate_name}

For example:

cargo test -p google-cloud-storage

The integration tests, located in tests/integration, run against live GCP services to validate the generated code.

Linter

To run the linter for the entire workspace, use the following command:

cargo clippy

To run the linter for a particular crate, use the following command:

cargo clippy -p ${crate_name}

For example:

cargo clippy -p google-cloud-storage

Code Formatter

To format the code for the entire workspace, use the following command:

cargo fmt

To format a crate use:

cargo fmt -p ${crate_name}

For example:

cargo fmt -p google-cloud-storage

Development Conventions

Setting up the Development Environment

  • Install rustc, rustfmt, clippy, and cargo using rustup.
  • Run cargo build and cargo test to verify the setup.

Forks and Pull Requests

  • Create a fork of the google-cloud-rust repository.
  • Create a branch for your changes.
  • Make your changes and commit them with a descriptive message.
  • The commit message should follow the "Conventional Commits" specification.
  • Push your changes to your fork.
  • Create a pull request from your fork to the main branch of the google-cloud-rust repository.
  • The PR body should include a detailed description of the changes.
  • The PR will be reviewed by the maintainers.

Generated Code Maintenance

  • Most of the code is generated by the sidekick tool.
  • Do not edit the generated code directly.
  • To update the generated code, you need to modify the generator templates or the service definitions.

Asynchronous Programming

All remote procedure calls (RPCs) are asynchronous and are designed to work with the Tokio runtime.

Error Handling

The libraries provide robust error handling, with a focus on providing clear and actionable error messages.

Retry and Polling Policies

The libraries include configurable policies for retrying failed requests and for polling the status of long-running operations. These policies can be customized by the application.

Contribution Guidelines

Contributions are welcome. The CONTRIBUTING.md file provides detailed instructions for contributors. Key documents for contributors include:

  • doc/contributor/howto-guide-set-up-development-environment.md
  • ARCHITECTURE.md