kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/go/extractors/config/preprocessor/README.md (about)

     1  # Build Config Preprocessing
     2  
     3  A number of builders require custom modification to a repo's build config before
     4  Kythe extraction will work correctly.
     5  
     6  ## Preprocessor
     7  
     8  This is the top level binary for doing preprocessing.  The default operation is
     9  simply `./preprocess <build-file>`, which will detect what format the build file
    10  is in and perform necessary steps.
    11  
    12  ## Invoking via docker / Cloud Build
    13  
    14  Insert the following step into your Cloud Build to preprocess a `pom.xml` or
    15  `build.gradle` file for use with Kythe extraction:
    16  
    17  ```
    18  - name: 'gcr.io/kythe-public/build-preprocessor'
    19    args: ['/workspace/path/to/pom.xml']
    20  ```
    21  
    22  If your repo is not copied to `/workspace/` but instead lives in another volume,
    23  you will have to specify the volume in your build step:
    24  
    25  ```
    26  - name: 'gcr.io/kythe-public/build-preprocessor'
    27    args: ['/other/volume/pom.xml']
    28    volumes:
    29      - name: 'volname'
    30        path: '/other/volume/'
    31  ```
    32  
    33  ## Specific Builders
    34  
    35  ### Gradle
    36  
    37  In order to run Kythe extraction on a gradle repo, we must first modify the
    38  `build.gradle` file to hook into a separate javac wrapper binary.
    39  `gradle_build_modifier.go` takes an input `build.gradle` file and appends the
    40  bits necessary for replacing javac calls with Kythe's `javac-wrapper.sh`.
    41  
    42  ```
    43  allprojects {
    44    gradle.projectsEvaluated {
    45      tasks.withType(JavaCompile) {
    46        options.fork = true
    47        options.forkOptions.executable = '/opt/kythe/extractors/javac-wrapper.sh'
    48      }
    49    }
    50  }
    51  ```
    52  
    53  If the input file already contains a reference to
    54  `options.forkOptions.executable`, then `gradle_build_modifier.go` does nothing.
    55  
    56  #### Future work
    57  
    58  The current implementation uses simple string-based matching, without actually
    59  understanding the structure.  If that becomes necessary in the future, it might
    60  be better to use the existing Java libraries for `org.codehaus.groovy.ast` to
    61  properly parse the build.gradle file and have more precise picture.  In
    62  particular `org.codehaus.groovy.ast.CodeVisitorSupport` might be sufficient.
    63  Ideally we find such a library in golang.
    64  
    65  ### Maven
    66  
    67  Maven's build config is handled by `pom_xml_modifier.go`.  One notable
    68  difference between gradle and maven here is that gradle actually embeds the
    69  reference to the javac wrapper directly in the build file, while the
    70  modifications to the maven pom xml file merely allow future configuration at
    71  runtime.
    72  
    73  The example snippet it drops in is:
    74  
    75  ```
    76  <build>
    77    <plugins>
    78      <plugin>
    79        <groupId>org.apache.maven.plugins</groupId>
    80        <artifactId>maven-compiler-plugin</artifactId>
    81        <version>3.7.0</version>
    82        <configuration>
    83          <source>1.8</source>
    84          <target>1.8</target>
    85        </configuration>
    86      </plugin>
    87    </plugins>
    88  </build>
    89  ```