From 659ee55b55609b53fcc0ef0d46001cc6fe2062d8 Mon Sep 17 00:00:00 2001 From: petroseskinder Date: Mon, 16 Oct 2017 00:31:36 -0400 Subject: [PATCH 1/4] Makes ergonomic changes to JavaSourceFileParserCli and adds documentation to lang/ --- lang/BUILD | 7 +++++++ lang/README.md | 17 ++++++++++++++++- .../java/com/google/devtools/build/bfg/BUILD | 6 +----- .../build/bfg/JavaSourceFileParserCli.java | 8 +++++--- 4 files changed, 29 insertions(+), 9 deletions(-) create mode 100644 lang/BUILD diff --git a/lang/BUILD b/lang/BUILD new file mode 100644 index 0000000..7ee2540 --- /dev/null +++ b/lang/BUILD @@ -0,0 +1,7 @@ +licenses(["notice"]) # Apache 2.0 + +java_binary( + name = "JavaSourceFileParserCli", + main_class = "com.google.devtools.build.bfg.JavaSourceFileParserCli", + runtime_deps = ["//lang/java/src/main/java/com/google/devtools/build/bfg:JavaSourceFileParser"], +) diff --git a/lang/README.md b/lang/README.md index f9d9627..2659b41 100644 --- a/lang/README.md +++ b/lang/README.md @@ -1 +1,16 @@ -A directory for language-specific parsers. +# Language Specific Parsers + +This directory contains a set of language-specific parsers, that can be used to generate a class and file level dependency graph of your project. It outputs this dependency graph as a protobuff. For users of bfg, this dependency graph can be used to generate your BUILD files. + +We currently only support Java. However, we plan to add Scala support, and welcome contributions for other languages. + +### Usage + +```bash + +bazel run //lang:JavaSourceFileParserCli + +``` + +TODO(bazel-devel): what do the command line options mean??? There is a TODO in the Cli asking how the files will be obtained. + diff --git a/lang/java/src/main/java/com/google/devtools/build/bfg/BUILD b/lang/java/src/main/java/com/google/devtools/build/bfg/BUILD index bc71367..aa5486b 100644 --- a/lang/java/src/main/java/com/google/devtools/build/bfg/BUILD +++ b/lang/java/src/main/java/com/google/devtools/build/bfg/BUILD @@ -30,10 +30,6 @@ java_library( "//thirdparty/jvm/com/google/guava", "//thirdparty/jvm/org/eclipse/jdt:org_eclipse_jdt_core", ], + visibility = ["//lang:__subpackages__"], ) -java_binary( - name = "JavaSourceFileParserCli", - main_class = "com.google.devtools.build.bfg.JavaSourceFileParserCli", - runtime_deps = [":JavaSourceFileParser"], -) diff --git a/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java b/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java index 581d6ef..af5ce20 100644 --- a/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java +++ b/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java @@ -36,8 +36,9 @@ import protos.com.google.devtools.build.bfg.Bfg; /** - * Entry point to BFG java source file parser. Given a list of source files, it prints a graph viz - * dot file representing the class level dependencies between these source files. + * Entry point to the BFG java source file parser. Given a list of source files, + * it obtains the class and file level dependencies between the files, generates a + * dependency graph, and outputs this graph as a protobuff. */ public class JavaSourceFileParserCli { @@ -73,7 +74,8 @@ private void run(String[] args) throws Exception { } catch (CmdLineException e) { if (sourceFiles.isEmpty()) { System.err.println("Must provide file names to parse."); - } else { + //TODO(bazel-team) print example usage of the class + } else { System.err.println(e.getMessage()); } e.getParser().printUsage(System.err); From c9979edef1a651be9a1317dd2f15264bad2ed65f Mon Sep 17 00:00:00 2001 From: petroseskinder Date: Mon, 16 Oct 2017 04:37:08 -0400 Subject: [PATCH 2/4] Makes running Bfg java_binary target more ergonomic --- src/BUILD | 12 ++++++++++++ src/main/java/com/google/devtools/build/bfg/BUILD | 10 +++------- src/main/java/com/google/devtools/build/bfg/Bfg.java | 1 + 3 files changed, 16 insertions(+), 7 deletions(-) create mode 100644 src/BUILD diff --git a/src/BUILD b/src/BUILD new file mode 100644 index 0000000..44bb61c --- /dev/null +++ b/src/BUILD @@ -0,0 +1,12 @@ +licenses(["notice"]) # Apache 2.0 + +package(default_visibility = [ + "//visibility:private", +]) + +java_binary( + name = "bfg", + main_class = "com.google.devtools.build.bfg.Bfg", + stamp = 1, + runtime_deps = ["//src/main/java/com/google/devtools/build/bfg:Bfg"], +) diff --git a/src/main/java/com/google/devtools/build/bfg/BUILD b/src/main/java/com/google/devtools/build/bfg/BUILD index fc8a7e9..a2b3167 100644 --- a/src/main/java/com/google/devtools/build/bfg/BUILD +++ b/src/main/java/com/google/devtools/build/bfg/BUILD @@ -76,13 +76,9 @@ java_library( "//thirdparty/jvm/com/google/guava", "//thirdparty/jvm/com/google/re2j", ], -) - -java_binary( - name = "bfg", - main_class = "com.google.devtools.build.bfg.Bfg", - stamp = 1, - runtime_deps = [":Bfg"], + visibility = [ + "//src:__subpackages__", + ], ) java_library( diff --git a/src/main/java/com/google/devtools/build/bfg/Bfg.java b/src/main/java/com/google/devtools/build/bfg/Bfg.java index 2bf330f..a0cd743 100644 --- a/src/main/java/com/google/devtools/build/bfg/Bfg.java +++ b/src/main/java/com/google/devtools/build/bfg/Bfg.java @@ -175,6 +175,7 @@ private static Pattern compilePattern(CmdLineParser cmdLineParser, String patter } } + //TODO(bazel-devel): actually print what the intended usage is. private static void explainUsageErrorAndExit(CmdLineParser cmdLineParser, String message) { System.err.println(message); cmdLineParser.printUsage(System.err); From c31bbae8ec4e99d7ac11ff5cb7123ae61858a289 Mon Sep 17 00:00:00 2001 From: petroseskinder Date: Mon, 16 Oct 2017 04:37:40 -0400 Subject: [PATCH 3/4] Creates skeleton of the project documentation --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3367dd9..5f3838a 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,64 @@ [![Build Status](http://ci.bazel.io/buildStatus/icon?job=BUILD_file_generator)](http://ci.bazel.io/job/BUILD_file_generator) -# BUILD File Generator +# BUILD File Generator (BFG) -BUILD File Generator generates Bazel BUILD files for Java code. +BUILD File Generator, or BFG for short, is a tool for generating Bazel BUILD files from one's source code. Instead of manually going through your project and creating BUILD files and their appropriate build rules, you can rely on BFG to do it for you! -1. It reads all `.java` files, and extracts the class dependency graph. -2. Computes the strongly connected components of the graph. -3. For each component, creates a `java_library` rule. +An example project can be found here. TODO + +### Why is it useful? + +Bazel promises fast and correct builds, _especially_ for incremental builds. Rather than rebuild your entire codebase, Bazel _only_ rebuilds what is necessary, the targets that you have changed. For the remainder of your code, it relies on cached versions. + +There is one caveat to this fast incremental performance, though. It is dependent on the granularity of your targets. At one extreme, the least granular end, you can define a single glob for your entire project. This would be the quickest way to get your project using Bazel. However, it comes at the cost of eradicating any of Bazel's incremental build performance. On the other end, you can try to manually define the most granular targets possible, a single rule per file, collapsing any cyclic dependencies into the same target. This would ensure you make use of Bazel's blazingly fast incremental builds. However, it is extremely tedious, and somewhat annoying to maintain. + +BFG automates this difficult tango. ## Usage -TODO +BFG is composed of two general components + +1. Language specific parsers (LSP) +2. The BFG binary + +The LSPs read your source code and generate a class dependency graph in the form of a protobuff. To generate your BUILD files, you pass the generated protobuff into the BFG binary. + +### Step 0: Installation Instructions + +To install BFG...TODO + +### Step 1: Using LSPs to generate dependency graphs + +TODO(bazel-devel): add explanation and valid example arguments. + +```bash +bazel run //lang:JavaSourceFileParserCli +``` + +This generates a protobuff at TODO. +TODO(bazel-devel): add clear protocol for how the protos are structured. Useful for other developers who may want to write LSPs. + +### Step 2: Generating BUILD files using BFG binary + +TODO(bazel-devel): add explanation and valid example arguments. + +```bash +bazel run //src:bfg +``` + +### Supported Languages + +We currently support Java projects. The next language on our roadmap is Scala. + +## Development + +### Contributing + +We welcome contributions! We generally prefer contributions that either (1) add features by extending BFG to other languages, (2) fix existing bugs, or (3) present bugs through the use of example projects. -## Adding or updating third-party dependencies +### Dependency Management -We use a third-party tool called [bazel-deps](https://github.com/johnynek/bazel-deps) -to manage our dependencies. All of our dependencies are listed in +To manage our dependencies, we use a third-party tool called [bazel-deps](https://github.com/johnynek/bazel-deps). All of our dependencies are listed in [`maven_deps.yaml`](maven_deps.yaml). bazel-deps provides tools to manage adding and updating dependencies in that file, and generates the Bazel build files for them in `thirdparty/jvm/`. From 9bacb72190d0b78548c68a65e68c6e53f440b1b2 Mon Sep 17 00:00:00 2001 From: petroseskinder Date: Mon, 16 Oct 2017 19:42:51 -0400 Subject: [PATCH 4/4] Fix typo and remove trailing spaces. --- README.md | 18 +++++++++--------- .../build/bfg/JavaSourceFileParserCli.java | 2 +- src/BUILD | 1 + 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5f3838a..425bdb0 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,16 @@ Bazel promises fast and correct builds, _especially_ for incremental builds. Rat There is one caveat to this fast incremental performance, though. It is dependent on the granularity of your targets. At one extreme, the least granular end, you can define a single glob for your entire project. This would be the quickest way to get your project using Bazel. However, it comes at the cost of eradicating any of Bazel's incremental build performance. On the other end, you can try to manually define the most granular targets possible, a single rule per file, collapsing any cyclic dependencies into the same target. This would ensure you make use of Bazel's blazingly fast incremental builds. However, it is extremely tedious, and somewhat annoying to maintain. -BFG automates this difficult tango. +BFG automates this difficult tango. ## Usage -BFG is composed of two general components +BFG is composed of two general components -1. Language specific parsers (LSP) +1. Language specific parsers (LSP) 2. The BFG binary -The LSPs read your source code and generate a class dependency graph in the form of a protobuff. To generate your BUILD files, you pass the generated protobuff into the BFG binary. +The LSPs read your source code and generate a class dependency graph in the form of a protobuf. To generate your BUILD files, you pass the generated protobuf into the BFG binary. ### Step 0: Installation Instructions @@ -29,13 +29,13 @@ To install BFG...TODO ### Step 1: Using LSPs to generate dependency graphs -TODO(bazel-devel): add explanation and valid example arguments. +TODO(bazel-devel): add explanation and valid example arguments. ```bash bazel run //lang:JavaSourceFileParserCli ``` -This generates a protobuff at TODO. +This generates a protobuf at TODO. TODO(bazel-devel): add clear protocol for how the protos are structured. Useful for other developers who may want to write LSPs. ### Step 2: Generating BUILD files using BFG binary @@ -48,13 +48,13 @@ bazel run //src:bfg ### Supported Languages -We currently support Java projects. The next language on our roadmap is Scala. +We currently support Java projects. The next language on our roadmap is Scala. ## Development -### Contributing +### Contributing -We welcome contributions! We generally prefer contributions that either (1) add features by extending BFG to other languages, (2) fix existing bugs, or (3) present bugs through the use of example projects. +We welcome contributions! We generally prefer contributions that either (1) add features by extending BFG to other languages, (2) fix existing bugs, or (3) present bugs through the use of example projects. ### Dependency Management diff --git a/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java b/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java index af5ce20..d870567 100644 --- a/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java +++ b/lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java @@ -38,7 +38,7 @@ /** * Entry point to the BFG java source file parser. Given a list of source files, * it obtains the class and file level dependencies between the files, generates a - * dependency graph, and outputs this graph as a protobuff. + * dependency graph, and outputs this graph as a protobuf. */ public class JavaSourceFileParserCli { diff --git a/src/BUILD b/src/BUILD index 44bb61c..08b307a 100644 --- a/src/BUILD +++ b/src/BUILD @@ -10,3 +10,4 @@ java_binary( stamp = 1, runtime_deps = ["//src/main/java/com/google/devtools/build/bfg:Bfg"], ) +