Skip to content
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.

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

docs(examples): Add example of using a src dir and separate tests dir with gazelle #1842

Open
wants to merge 11 commits into
base: main
Choose a base branch
from

Conversation

dougthor42
Copy link
Collaborator

Add an example of using a src dir and separate tests dir and
having gazelle generate targets correctly so that tests can be run.

Fixes #1775.

@dougthor42 dougthor42 marked this pull request as ready for review April 11, 2024 18:53
@dougthor42 dougthor42 requested a review from rickeylev as a code owner April 11, 2024 18:53
@dougthor42
Copy link
Collaborator Author

I can't seem to figure out why builds are failing. Any tips?

If I run bazel test //... from the new example directory, things run just fine.

$ cd examples/bzlmod_python_src_dir_with_separate_tests_dir/
$ bazel test //...
INFO: Analyzed 10 targets (4 packages loaded, 24 targets configured).
INFO: Found 7 targets and 3 test targets...
INFO: Elapsed time: 20.303s, Critical Path: 18.58s
INFO: 13 processes: 7 internal, 2 local, 4 processwrapper-sandbox.
INFO: Build completed successfully, 13 total actions
//:gazelle_python_manifest.test                                          PASSED in 0.2s
//:requirements_test                                                     PASSED in 16.2s
//tests:test_my_python_module                                            PASSED in 0.6s

Executed 3 out of 3 tests: 3 tests pass.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these are.

If I run from the git repo root, I get the same failures seen in CI (unknown repo 'pypi').

$ cd -
/c/dev/rules_python
$ bazel test //...
ERROR: Skipping '//...': error loading package under directory '': error loading package 'examples/bzlmod_python_src_dir_with_separate_tests_dir': Unable to find package for @@[unknown repo 'pypi' requested from @@]//:requirements.bzl: The repository '@@[unknown repo 'pypi' requested from @@]' could not be resolved: No repository visible as '@pypi' from main repository.
ERROR: error loading package under directory '': error loading package 'examples/bzlmod_python_src_dir_with_separate_tests_dir': Unable to find package for @@[unknown repo 'pypi' requested from @@]//:requirements.bzl: The repository '@@[unknown repo 'pypi' requested from @@]' could not be resolved: No repository visible as '@pypi' from main repository.
INFO: Elapsed time: 25.549s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Couldn't start the build. Unable to run tests

From what I can tell, the only differences between this example and bzlmod or bzlmod_build_file_generation is that this example:

  1. Doesn't have a WORKSPACE file
  2. Uses pypi for the hub name instead of pip.

But I tried making both of those edits locally and still got the same error.

Note: I'm ignoring the MacOS and Windows CI failures for now.

@aignas
Copy link
Collaborator

aignas commented Apr 17, 2024

Please run the pre-commit hooks that will update .bazelignore, which should fix the errors seen in the tests running from the root.

Edit: or the .bazelrc, can't remember which one in this case.

@dougthor42
Copy link
Collaborator Author

Thanks. Turns out it's both .bazelrc and .bazelignore.

I also noticed that the pre-commit hook update-deleted-packages doesn't appear to work correctly, so I've opened #1858 with details.

Copy link
Collaborator

@aignas aignas left a comment

Choose a reason for hiding this comment

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

Sorry, I thought I had submitted these review comments, but it seems that I had not done this. Happy to move this forward.

I think we may want to add a bazel-in-bazel integration test somewhere here.

@@ -0,0 +1,69 @@
# Define metadata about this repository/project.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Having an empty WORKSPACE file may fix some of the issues you saw with the pre-commit hook, I think.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Hmm... still no dice. Same issue.

Given that CI is passing, I'm not too concerned about the pre-commit check. My assumption is that it's something specific to my computer/setup rather than specific to this branch, as pre-commit run --all-files also fails on the latest main commit 3730803.

Comment on lines 10 to 14
# In the old WORKSPACE file, this would be 4 items:
# 1. `load` the http_archive rule
# 2. run the http_archive rule, grapping rules_python from github
# 3. load the py_repositories target from rules_python
# 4. execute py_respositories()
Copy link
Collaborator

Choose a reason for hiding this comment

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

We could just link to the relevant example (e.g. pip_parse or pip_parse_vendored).

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Relative file references added, but I kept the original list because I find it easier to follow if I don't have to jump around to various other examples. LMK if you feel strongly about removing the list.

)

# Install rules_python, which allows us to define how bazel should work with python files.
# See https://github.com/bazelbuild/rules_python/blob/main/examples/bzlmod/MODULE.bazel
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why not use relative file references? At least in vim users could use gf to go to the file instantly and I hope other editors might support something similar.

Suggested change
# See https://github.com/bazelbuild/rules_python/blob/main/examples/bzlmod/MODULE.bazel
# See ../bzlmod/MODULE.bazel

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

+1, updated here and for gazelle/README.md below.

Comment on lines 57 to 58
# Use the bazel downloader for pulling pypi packages.
experimental_index_url = "https://pypi.org/simple",
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nice!

requirements_lock = "//:requirements.lock",
)

# Same as WORKSPACE install_deps() - actually install the python deps.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is not technically correct. Here we just expose the repo to be used by the module and the install happens lazily by bazel. I do think the intention is good - to draw parallels between WORKSPACE and MODULE.bazel, but this example might be something that people may read without any WORKSPACE knowledge.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Ah, good to know! Updated, PTAL and check for correctness.

Copy link
Collaborator Author

@dougthor42 dougthor42 left a comment

Choose a reason for hiding this comment

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

I thought I had submitted these review comments

I do the same things all the time. I really wish GitHub had some "you have an unsubmitted review pending" notification or something.

But anyway, thanks for the comments! And don't worry about the delay! You've already been super responsive elsewhere, and adding a new example is a low priority.

I think we may want to add a bazel-in-bazel integration test somewhere here.

Can you elaborate on this?

@@ -0,0 +1,69 @@
# Define metadata about this repository/project.
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Hmm... still no dice. Same issue.

Given that CI is passing, I'm not too concerned about the pre-commit check. My assumption is that it's something specific to my computer/setup rather than specific to this branch, as pre-commit run --all-files also fails on the latest main commit 3730803.

)

# Install rules_python, which allows us to define how bazel should work with python files.
# See https://github.com/bazelbuild/rules_python/blob/main/examples/bzlmod/MODULE.bazel
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

+1, updated here and for gazelle/README.md below.

Comment on lines 10 to 14
# In the old WORKSPACE file, this would be 4 items:
# 1. `load` the http_archive rule
# 2. run the http_archive rule, grapping rules_python from github
# 3. load the py_repositories target from rules_python
# 4. execute py_respositories()
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Relative file references added, but I kept the original list because I find it easier to follow if I don't have to jump around to various other examples. LMK if you feel strongly about removing the list.

requirements_lock = "//:requirements.lock",
)

# Same as WORKSPACE install_deps() - actually install the python deps.
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Ah, good to know! Updated, PTAL and check for correctness.

@aignas
Copy link
Collaborator

aignas commented May 30, 2024

I've been thinking about this PR and how do we organise it together with other gazelle docs that we have. We are running short on CI executors so just adding this example into the CI is not so straight forward. For running bazel-in-bazel integration tests we use https://github.com/bazel-contrib/rules_bazel_integration_test. However, this makes our tests slow to execute as they become yet another thing that needs to be executed when we do bazel test //....

What is more, if we merge this PR, does it trump the other example on build_file_generation? What is the expected example people are to follow? Given that the Python community is recommending this structure, does it mean that we should follow their recommendations as well? bazel has different limitations and benefits and I am wondering about the tradeoffs here and in other places.

Given that this example may be more complex than the existing gazelle example I would be +1 on replacing the existing example with this or merging them in some way.

Sorry that this is dragging so long, but I am a bit lost with how we teach our users to use gazelle and it seems that more and more people are starting to use it, so your PR is a great addition to the knowledge base, but I am concerned that if we are not running CI on it, it will become stale and will cause new issues about "stale example".

Am I overthinking it here? What are your thoughts? We can have a call to chat this because I do think that having an async messaging is slowing us down. Shall we get in touch on the bazel slack?

@dougthor42
Copy link
Collaborator Author

I don't have a slack account, sorry. I could do Google Meet if that works for you.

No, you're not overthinking this at all - you have great concerns and know a bunch more about the project than I do. For example, I didn't know about bazel-in-bazel (though I should have suspected, haha) or about how there are a limited number of CI executors.


does it trump the other example? What is the expected example people are to follow?

I would say that there should be a single "main" example to follow, ideally with a limited feature set consisting of the most common use cases (how many projects need whl_mods from the start?)

IMO the feature set for the main example should be:

  • python toolchain (hermetic python)
  • pip.parse, obviously
  • gazelle python manifest
  • gazelle and some common directives

We don't need the requirement locking (compile_pip_requirements). At least IME, large projects already have that via tools like poetry or uv.


should Bazel follow the python community recommendation for project structure?

I'd say that depends on the goals of rules_python.

Do people want rules_python to be used in more and more open-source projects (eg: get numpy to switch from meson to bazel; get flask to use it; have it be the default for greenfield projects)? If so, then the "main" example should follow community recommendation for project structure, and modifying as necessary to address the Basel-specific directory structure needs.

Or is rules_python targeting more closed-source systems, like Google and Uber and Dropbox, etc.? If so, then the "main" example should probably follow the a structure that more closely reflects what is done in corporate environs (which would be harder to figure out).


I would be +1 on replacing the existing example with this or merging them in some way

Same. When we make a decision I can work on that.


I am concerned that if we are not running CI on it, it will become stale

+100 on that. Incorrect docs can be worse than no docs, haha.

@aignas aignas self-assigned this May 30, 2024
@aignas aignas added the gazelle Gazelle plugin related issues label Jun 4, 2024
@dougthor42
Copy link
Collaborator Author

Decision from our video chat: integrate this example into the existing examples/bzlmod_build_file_generation example with a dir structure somewhat like:

./examples/bzlmod_build_file_generation
+ pattern1/
    + (the current example)
+ pattern2/
    + the example from this PR
+ README.md  # includes descriptions of the patterns

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
gazelle Gazelle plugin related issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Example of using a "src" dir with gazelle
2 participants