Document usage of JavaSourceFileParserCli and Bfg.

[greggdonovan]

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

[petroseskinder]

@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]

@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]

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]

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]

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]

@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]

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

[petroseskinder]

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

• https://github.com/wix-playground/scala-bazel-oss-demo
• https://github.com/ittaiz/bazel-scala-getting-started

[petroseskinder]

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

[prestonvanloon]

+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]

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 :\ )