Skip to content

GEMINI.md

Latest commit

 

History

History
222 lines (158 loc) · 6.66 KB

GEMINI.md

File metadata and controls

222 lines (158 loc) · 6.66 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.
  • Pub/Sub: The src/pubsub crate contains a client library for Google Cloud Pub/Sub.

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 tests for a particular crate, use the following command:

cargo test -p ${crate_name}

For example:

cargo test -p google-cloud-storage

Running Integration Tests

Integration tests are located in the tests directory (e.g., tests/integration, tests/integration-auth). They are often disabled by default because they run against live GCP services.

To run integration tests, you typically need to:

  1. Authenticate: Run gcloud auth application-default login to set up credentials.
  2. Set Environment Variables: Many tests require specific environment variables to be set (e.g., GOOGLE_CLOUD_PROJECT).

To run integration tests for a specific suite, you need to enable the corresponding feature.

For example, to run the general integration tests with required environment variables:

GOOGLE_CLOUD_PROJECT="$(gcloud config get project)"
env \
    GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    GOOGLE_CLOUD_RUST_TEST_SERVICE_ACCOUNT=rust-sdk-test@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com \
    GOOGLE_CLOUD_RUST_TEST_STORAGE_KMS_RING=us-central1 \
  cargo test -p integration-tests --features run-integration-tests

See doc/contributor/howto-guide-set-up-development-environment.md for more details on setting up resources for integration tests.

Linter

Our CI runs clippy with --deny warnings in different configurations to ensure full coverage. It is recommended to run both of the following commands locally:

To check the default build (which catches issues in #[cfg(not(test))] code paths):

cargo clippy --all-targets -- -D warnings

To check the build with tests enabled (includes #[cfg(test)] and test files):

cargo clippy --profile test -- -D warnings

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

cargo clippy -p ${crate_name} --all-targets -- -D warnings
cargo clippy -p ${crate_name} --profile test -- -D warnings

For example:

cargo clippy -p google-cloud-storage --profile test -- -D warnings

We run a comprehensive strict check as part of our CI that enforces stricter lints on all handwritten crates. This check is defined as a Cargo alias called clippy-strict in .cargo/config.toml.

To run these checks locally on all targeted handwritten crates, use the cargo alias clippy-strict:

cargo clippy-strict

To run this strict check for a specific crate, run standard cargo clippy with the same flags from the alias:

cargo clippy --all-features --no-deps -p google-cloud-storage -- -D missing_docs -D clippy::exhaustive_enums

Please refer to .cargo/config.toml for the authoritative list of crates and exact set of lint flags currently subject to these checks.

Important

When editing or adding code within any of the handwritten crates, you MUST run the strict clippy check (cargo clippy-strict for all crates or the specific command above for the modified crate) to ensure no new warnings are introduced.

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 librarian tool.
  • Do not edit the generated code directly.
  • To update the generated code, you need to modify the generator templates or the service definitions. See doc/contributor/howto-guide-generated-code-maintenance.md for details.

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