Skip to content

docs: explain default generation config in README.md #3388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 20, 2024
Merged

docs: explain default generation config in README.md #3388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b953dc3
docs: explain default generation config
JoeWang1127 Nov 20, 2024
923d3a6
add a prerequisite
JoeWang1127 Nov 20, 2024
c7a90e4
rephrase after code review
JoeWang1127 Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions hermetic_build/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,20 +18,36 @@ for additional instructions.

## Prerequisites

In order to generate a version for each library, a versions.txt has to exist
### Generation configuration

A generation configuration file is required to generate GAPIC Client Libraries.

Please refer to [Generation configuration yaml](#generation-configuration-yaml--generation-config-path---optional)
for more information.

### versions.txt
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, we would generate a versions.txt file if it does not exist. Can you confirm @diegomarquezp ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it is not generated. The scripts will just fail if not found.

sdk-platform-java/hermetic_build/library_generation/utils/utilities.py

Lines 124 to 142 in 1080de4

def prepare_repo(
gen_config: GenerationConfig,
library_config: List[LibraryConfig],
repo_path: str,
language: str = "java",
) -> RepoConfig:
"""
Gather information of the generated repository.
:param gen_config: a GenerationConfig object representing a parsed
configuration yaml
:param library_config: a LibraryConfig object contained inside config,
passed here for convenience and to prevent all libraries to be processed
:param repo_path: the path to which the generated repository goes
:param language: programming language of the library
:return: a RepoConfig object contained repository information
:raise FileNotFoundError if there's no versions.txt in repo_path
:raise ValueError if two libraries have the same library_name
"""

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, thanks for the quick response!

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file is required, per

sdk-platform-java/hermetic_build/library_generation/utils/utilities.py

Line 164 in 7d6d66a

raise FileNotFoundError(f"{versions_file} is not found.")

Though I think we can create an empty file if not exist since we didn't check the contents.

I'll create a follow-up issue.


In order to generate a version for each library, a `versions.txt` has to exist
in `repository-path`.
Please refer to [Repository path](#repository-path--repositorypath---optional)
for more information.

## Parameters to generate a repository using the docker image

### Generation configuration yaml (`generation-config-path`)
### Generation configuration yaml (`generation-config-path`), optional
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a sentence before this section mentioning something like "All the parameters are optional, but a generation_config.yaml is required"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this to Prerequisites.


An absolute or relative path to a configuration file containing parameters to
generate the repository.
Please refer to [Configuration to generate a repository](#configuration-to-generate-a-repository)
for more information.

The default value is `$(pwd)/generation_config.yaml`, i.e., `generation_config.yaml`
in the current working directory.

This will raise `FileNotFoundError` if the specified generation config does not
exist or, in case `generation-config-path` is not specified, the default
generation config does not exist.

### Repository path (`repository-path`), optional

The path to where the generated repository goes.
Expand All @@ -41,8 +57,8 @@ For example, `cd google-cloud-java && python /path/to/entry_point.py ...` withou
specifying the `--repository_path` option will modify the `google-cloud-java`
repository the user `cd`'d into.

Note that versions.txt has to exist in `repository_path` in order to generate
right version for each library.
Note that `versions.txt` has to exist in `repository_path` in order to generate
the right version for each library.
Please refer [here](go/java-client-releasing#versionstxt-manifest) for more info
of versions.txt.

Expand Down
26 changes: 8 additions & 18 deletions hermetic_build/library_generation/cli/entry_point.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,28 +78,18 @@ def generate(
api_definitions_path: str,
):
"""
Compare baseline generation config and current generation config and
generate changed libraries based on current generation config.
Generate libraries based on a generation config.

If baseline generation config is not specified but current generation
config is specified, generate all libraries if `library_names` is not
specified, based on current generation config.

If current generation config is not specified but baseline generation
config is specified, raise FileNotFoundError because current generation
config should be the source of truth of library generation.

If both baseline generation config and current generation config are not
specified, generate all libraries based on the default generation config,
which is generation_config.yaml in the current working directory.
If the `generation-config-path` is not specified the default generation
config, `$(pwd)/generation_config.yaml`, will be used.

If `library_names` is specified, only libraries whose name can be found in
the current generation config or default generation config, if current
generation config is not specified, will be generated. Changed libraries
will be ignored even if baseline and current generation config are
specified.
the generation config will be generated; otherwise all libraries in the
generation config will be generated.

Raise FileNotFoundError if the default config does not exist.
:raise FileNotFoundError if the specified generation config does not exist
or, in case `generation-config-path` is not specified, the default
generation config does not exist.
"""
__generate_repo_impl(
generation_config_path=generation_config_path,
Expand Down
Loading