-
Notifications
You must be signed in to change notification settings - Fork 4.1k
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
Clearly document the prelude file #1674
Comments
Not really related but I wish could be fixed together: in-bazel error messages of BUILD files are messy when prelude is used. Steps to reproduce:
You get error messages that look like:
which is extremely messy, and I doubt the users will notice that the correct diagnosis is in the first line of hundreds lines of error messages. |
@ahyangyi Thanks, we've now fixed the error messages. |
Thank you, @laurentlb ! |
What are some use cases for a prelude? Is this a feature bazel is trying to get rid of? I have seen adding load statements for language rules, but I would rather be able to put those rules into global scope in a WORKSPACE instead. Is it free to have an unused load in a BUILD file? |
The prelude file is not very well supported. Inside Google, we rarely use it (we used it a few times to assist us during a migration). The prelude file doesn't play well with incremental builds: if you modify it (or any of its dependencies), every package will have to be reloaded. To automatically removed unused load statements from you BUILD files, try buildozer (https://github.com/bazelbuild/buildtools/tree/master/buildozer): |
Laurent, could you confirm my understanding of the prelude?
Any advice on where this should be documented? Perhaps where we explain the default environment of a BUILD file? |
All correct. We should recommend using only In the website, we can have a new page under |
The prelude should not have its own page---we do not want to draw attention to it. It should be a footnote in a page describing the predeclared environment of a BUILD file: Starlark core operators, functions (glob, select ...), build rules, and so on. Where in the source code would one add such a page? //site/_layouts/...? |
The documentation of BUILD files is here: https://docs.bazel.build/versions/master/build-ref.html#BUILD_files |
That page is the introduction to the core concepts. It is not the appropriate place for reference material on the predeclared environment of a BUILD file. Where would one add such a page? |
We can create a new page under |
Yes! But where in the repository would the page's file reside? |
I would add that the current implicit textual insertion creates confusing error messages in case of bugs... which can only be solved when you replace it with implicit load-like semantics. Hence, a change like that would definitely be noticed by me, but it's for the better! |
I meant to say "noticed by Starlark logic". But it's good to know the change will make at least one person happy. :) |
I was about to send a CL to add this new file, but I realized it would be a case of "all the existing X are bad, let me create another one", where X in this case is "pages documenting the environment". This is a step in the wrong direction. We desperately need to carefully reorganize our API reference docs (ideally without breaking URLs). The problem is that they are partly generated by a program, so this is actually a somewhat subtle logic change not a doc edit. We cannot entrust the task of organizing docs to our doc tooling (e.g. stardoc). It can generate parts of the docs but a human editor must decide how they are stitched together. Also, every document should explain how to edit it, even if that means editing .java code. Ideally we would have one page with a complete index or ToC, organized into several logical sections, with each section being an explanation of the grouping and a set of links to a single page that explains all functions in that section fully.
Core built-ins are specified at https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions. That doc needs a table of contents. (The one at go.starlark.net from which it was copied has one; not sure how it got lost.) They are also documented (from Java code) at https://docs.bazel.build/versions/master/skylark/lib/globals.html, but this doc also contains lots of things that don't belong. Also, we should call them predeclared built-ins, not globals. Common functions (select, depset) are included here, along with core built-ins and .bzl things: The native package is documented here Built-ins common to BUILD and .bzl files: select, depset, ... This doc is a mix of native.x functions plus select (but no depset). Makes no sense. We should prefer fewer, larger pages, over many smaller ones (especially many non-intuitive groupings---I spent half my time clicking to find the seemingly arbitrary page on which a given function appears.) Browsers are quite capable of rendering big docs, they work best on slower networks, and users can jump around more easily. |
A couple corrections to the above:
Ever since c93ef7b, it's been local to a repo, so that the prelude definitions don't bleed between your dependencies and your main repo.
|
Thank you for contributing to the Bazel repository! This issue has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this issue is still relevant and should stay open, please post any comment here and the issue will no longer be marked as stale. |
This issue has been automatically closed due to inactivity. If you're still interested in pursuing this, please post |
I just came across the concept of the bazel prelude while trying to resolve another issue (#1673), and I could not find any explanation of how the prelude is supposed to work anywhere. Searching bazel.io turns up nothing, and the google groups have only two passing mentions. It does appear to be used in another bazel project, as the Skydoc documentation instructs users to insert a snippet into their prelude. I think it would be helpful to get an explanation of what the prelude is for and how to use it effectively.
The text was updated successfully, but these errors were encountered: