Generate client libraries with Bazelisk (Automotive)

Client libraries are language-specific interfaces for an API. This document describes how to use Bazelisk, a launcher for Bazel, to generate client libraries for the Routes API for Automotive in a variety of programming languages. Bazelisk ensures that the correct version of Bazel is used to execute the build commands.

The code needed to generate the libraries is hosted in a private Gerrit repository. For an explanation of how client libraries work, see Client libraries explained.

Prerequisites

Software requirements

Install the following:

Permissions requirements

  • Access to the repository is provided to members of a specific <partner>@google.com group, which is managed by a representative of your company. To get added to this group, reach out to either your company's point of contact or Google business partner.

Step 1: Access Gerrit

To access Gerrit:
  1. Make sure you completed the repository permission requirements listed in the Prerequisites section.
  2. Create a Google Account with a corporate email address by following the instruction in Create a Google Account.
    • When creating a Google Account, make sure you aren't logged in to gmail.com or another Google domain services account before visiting the Google Account Sign-in page. To ensure a clean profile, close and restart your browser, and open an incognito (private) browsing window.
    • When requesting access for others, create an account for each individual who needs access. Then send the list of new Google Accounts to your Google business partner. Your business partner will add the email addresses to the appropriate access groups.
  3. Using the Google Account you just created, go to https://partner-code.googlesource.com. When you access the Gerrit host, a user will be created and automatically logged in for you.
  4. From https://partner-code.googlesource.com, click Generate Password. Follow the on-screen prompts to select your Google Account, allow googlesource.com access, and follow other on-screen instruction.
  5. When presented with a script, copy and paste the script into your terminal.

Step 2: Clone the repositories

In this step, you will clone the googleapis and routes-auto-early-access repositories.

  1. Clone the routes-auto-early-access repository: 
    git clone https://partner-code.googlesource.com/routes-auto-early-access
  2. Clone the public Google googleapis repository: 
    git clone https://github.com/googleapis/googleapis.git

Step 3: Merge the repositories

In this step, you will move the routes-auto-early-access/google/maps/routing/v2 subdirectory into googleapis/google/maps/routing/v2.

  1. After cloning the repos, make sure your present working directory (pwd) includes both routes-auto-early-access and googleapis subdirectories. 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Create a routing/v2 directory in the target location and copy routing/v2 into googleapis/google/maps/routing/v2: 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

To confirm the routing/v2 directory successfully merged into the googleapis/google/maps/routing/v2 directory, go to googleapis/google/maps/routing/v2. The folder should contain proto files, a BUILD.bazel file, and other files necessary for the build.

Step 4: Build a client library using Bazelisk

To build the client library for a particular language, identify the build target for that language in the BUILD.bazel file (at googleapis/google/maps/routing/v2/BUILD.bazel) and build that target. You can find the target name inside the <LANGUAGE>_gapic_assembly_pkg objects. See Building one target in the Bazel documentation for more information.

For example, to build the Java client library, do the following:

  1. Change into the googleapis directory: 
    cd googleapis
  2. Run the following command: 
    bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java

    This command generates the Java client library at googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

For your convenience, the following table lists the build commands for each available language.

Language Bazelisk build command
Java bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java
Go bazelisk build google/maps/routing/v2:gapi-cloud-maps-routing-v2-go
PHP bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-php
Ruby bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-ruby
C# bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-csharp
Node bazelisk build google/maps/routing/v2:maps-routing-v2-nodejs

Incorporate updates when there are new releases

When there are new releases to the API, you need to rebuild the client libraries. Assuming you already cloned the repos following the instruction in the previous sections, do the following for new releases:

  1. Change into the present working directory that contains both repositories: 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Remove the previous instance of routing/v2 inside googleapis/google/maps: 
    rm -rf googleapis/google/maps/routing/v2
  3. Go to both the routes-auto-early-access and googleapis repositories and run git pull to get the latest updates.
  4. Copy routing/v2 into googleapis/google/maps/routing/v2, similar to before: 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

    To confirm the routing/v2 repository successfully merged into the googleapis/google/maps/routing/v2 directory, go to googleapis/google/maps/routing/v2. The folder should contain proto files, a BUILD.bazel file, and other files necessary for the Bazel build.

  5. Run the Bazelisk build commands listed in the earlier section Step 4: Build a client library using Bazelisk.

Generate Javadocs for the Java client library

The client library gives you the ability to call the Routes API for Automotive using the classes and methods specific to the language. Unfortunately, the output doesn't include the Javadoc documentation for the client library. This section explains how to generate the Javadoc for the Java client library.

Prerequisites

To build the Javadoc:

  1. Ensure you have compatible versions of Gradle (8.0 or higher) and JDK (17 or lower) installed. You can check your installed versions by running ./gradlew --version and java -version in your terminal.

  2. The Java client library is built to the following tar.gz file, which you will need to extract: googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

    Assuming you're in the googleapis directory, run the following command, replacing /PATH/TO/PARENT/DIRECTORY with your chosen path for the extracted library:

    mkdir -p /PATH/TO/PARENT/DIRECTORY && tar -xzpf bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz -C /PATH/TO/PARENT/DIRECTORY

  3. Navigate to the parent directory:

    cd /PATH/TO/PARENT/DIRECTORY

  4. From the google-cloud-maps-routing-v2-java directory, open the build.gradle files in each of the following directories:

    • gapic-google-cloud-maps-routing-v2-java/build.gradle
    • grpc-google-cloud-maps-routing-v2-java/build.gradle
    • proto-google-cloud-maps-routing-v2-java/build.gradle

    Ensure each contains the following tasks. Due to a bug, replace the existing two similar tasks and artifacts with this code:

    
task javadocJar(type: Jar, dependsOn: javadoc) {
  archiveClassifier.set('javadoc')
  from javadoc.destinationDir
}

task sourcesJar(type: Jar) {
  archiveClassifier.set('sources')
  from sourceSets.main.allSource
}

artifacts {
archives javadocJar
}

  5. Check that you're using Gradle 8.0 or higher: ./gradlew --version. If your version is 7, do the following: from the google-cloud-maps-routing-v2-java directory, delete the gradlew and gradlew.bat files. Then run gradle wrapper --gradle-version=8.0 to switch to 8.0.

  6. From the google-cloud-maps-routing-v2-java directory, use Gradle to build the Javadocs:

    ./gradlew build

    The generated Javadoc appears in these directories:

    • google-cloud-maps-routing-v2-java/gapic-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/grpc-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/proto-google-cloud-maps-routing-v2-java/build/docs/javadoc

  7. Open the overview-tree.html file of each directory using a web browser.