docs: there may be multiple BUILD files in a directory

[AlexTereshenkov]

Docs rendered locally:

[AlexTereshenkov]

Link tested.

[kaos]

For instance, you could store source code targets and
macros in different files to have better separation of concerns

The example seems to show having different targets in the files, which works fine, but the above text talks about macros, and that will not work. The files are not merged before parsing, so if you decalare a def my_macro(): ... in one, you can't call it from the other.

[kaos]

That is, they're parsed, and processed, individually, they will just share "namespace" for their respective targets, so they show up together..

[AlexTereshenkov]

Thanks, Andreas! Perhaps bringing macros into this wasn't worth it. I've updated the docs to use files and code targets; this should keep things simple.

[huonw]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

A couple of questions:

1. Do you use this in practice?
2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?

[kaos]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

I agree with ☝🏽

A couple of questions:

1. Do you use this in practice?

See this thread: https://chat.pantsbuild.org/t/16949338/is-there-a-way-to-exclude-an-arbitrary-build-target-at-runti#45196675-a2bb-4472-a837-e4de911f6898

2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?

[cognifloyd]

1. Do you use this in practice?

I use this in the StackStorm repo to separate tool resolve requirements from the primary code requirements targets:
https://github.com/StackStorm/st2/blob/master/BUILD.tools
https://github.com/StackStorm/st2/blob/master/BUILD

[AlexTereshenkov]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

A couple of questions:

1. Do you use this in practice?

2. The `BUILD.experimental` example sounds good; maybe we could use that as the only example?

3. Maybe we could also add an info/warning box that explicitly suggests that "one `BUILD` is usually what you want", too?

I am sorry for the late reply.

1. Do you use this in practice?

Yes, I do. We have some targets that I only want to become available at CI builds as there is some code generation done before Pants runs.

2. The `BUILD.experimental` example sounds good; maybe we could use that as the only example?

Definitely, I've updated the docs.

3. Maybe we could also add an info/warning box that explicitly suggests that "one `BUILD` is usually what you want", too?

I've added a sentence at the beginning of the paragraph to make it clearer.