search

bazelbuild / BUILD_file_generator

Generate BUILD files for your Java files
Apache License 2.0
39 stars 19 forks source link

Document usage of JavaSourceFileParserCli and Bfg. #21

Open greggdonovan opened 6 years ago

greggdonovan commented 6 years ago

We should add basic usage instructions for both tools and document how they interact.

petroseskinder commented 6 years ago

@greggdonovan, as you are developing the Scala portion, do you have an example project you are working with? I think a concrete example in say examples/ would make a stepwise improvement to documentation and development. (I reference the benefits to development in #14)

greggdonovan commented 6 years ago

@petroseskinder That's a great idea. I've been working against our giant internal Scalding monorepo in development, but that's not OSS.

However, we have an OSS project called Sahale that could make a good example to test on. That would also satisfy @davidstanke, as he is looking for more Scala+Bazel OSS projects to test against.

We could also start with a small synthetic project in examples/ that we could use for an e2e test.

petroseskinder commented 6 years ago

I like all ideas presented. I'll either search for another java project or write one myself.

An additional approach that could be useful, regardless of whether we take the OSS approach or the synthetic, is defining a set of key project/language features we support. In other words, a minimum criteria for a stable language specific parser.

When initially developing Bfg, our approach was to find a sufficiently complicated project and simply getting Bfg working against it. Concretely, this meant first getting Bfg to self host, and then for it to host Blaze (with human assistance).

This got development rolling, but it does make sense to be more explicit about what language features we support, and whether we support mixing of languages.

As far as the Scalding monorepo, do you expect for Bfg's generated BUILD files to build without any human modifications? That's another area that is ambiguous.

That would also satisfy @davidstanke, as he is looking for more Scala+Bazel OSS projects to test against.

Ah yes. I saw @davidstanke's post on bazel-discuss. He commented he wanted something to experiment with. I'm curious what he was in particular he was planning to experiment with.

greggdonovan commented 6 years ago

As far as the Scalding monorepo, do you expect for Bfg's generated BUILD files to build without any human modifications?

I hope so, but this is an ambitious goal. At minimum I think we'll need to make the logic to take a Scala file and determine the appropriate rule pluggable to accommodate some of our edge cases.

But, I'm happy to make getting Sahale - a much simpler project - to build without human modifications e2e as a first milestone.

cgrushko commented 6 years ago

I've been thinking of trying to migrate https://github.com/google/google-java-format, because (a) it doesn't use Bazel yet and (b) being Google, it's similar to the code we "trained" BFG on (e.g., not abstract test classes, no start imports).

petroseskinder commented 6 years ago

@cgrushko: I've been thinking of trying to migrate https://github.com/google/google-java-format, because (a) it doesn't use Bazel yet and (b) being Google, it's similar to the code we "trained" BFG on (e.g., not abstract test classes, no start imports).

By migrate, you mean you are running Bfg against it? Also, is your intention to have it eventually hosted on Bazel?

@greggdonovan: At minimum I think we'll need to make the logic to take a Scala file and determine the appropriate rule pluggable to accommodate some of our edge cases.

But, I'm happy to make getting Sahale - a much simpler project - to build without human modifications e2e as a first milestone.

That sounds good to me. How will we integrate these examples? Shall we take the approach of examples/ directory with synthetic or modified existing projects?

cgrushko commented 6 years ago

Yep, run BFG on, generate BUILD files and convince them they should switch.

petroseskinder commented 6 years ago

For scala at least, I think we can potentially make use of either:

petroseskinder commented 6 years ago

Gazelle provides Build File Generation for Go projects. The documentation is very thorough, and serves as a good example for this issue.

prestonvanloon commented 6 years ago

+1 for this. I'm trying to use this for the first time and I'm really struggling to figure out how to use it.

I'm a bit confused by the 2 step process and a dependency on buildozer. Couldn't this be run as a simple command like bazel run :gazelle? (I'm also thinking about jade, for you Googlers.)

It sure would be ideal to add a WORKSPACE import and a build target so that I could run bazel run :bfg rather than adding another binary to my PATH.

cgrushko commented 6 years ago

In the meanwhile, you might be interested in https://github.com/cgrushko/text/blob/master/migrating-gjf-to-bazel.md which documents how I migrated google-java-format to Bazel using a tool we wrote later, Jadep. (Jadep is used internally at Google, so is a little better supported than BFG :\ )