kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/cxx/extractor/README.md (about)

     1  ## Bazel C++ extractor
     2  
     3  An extractor that builds index files from a Bazel-based project. Extractor
     4  builds a kzip file for each `cc_library` and `cc_binary` in the project. This
     5  extractor based on Bazel
     6  [action_listener](https://docs.bazel.build/versions/master/be/extra-actions.html)
     7  rule.
     8  
     9  #### Usage
    10  
    11  These instructions assume the kythe is installed in /opt/kythe. If not, follow
    12  [installation](http://kythe.io/getting-started) instructions.
    13  
    14  Currently Bazel doesn't have a convenient way to use action listener outside of
    15  a project. So first you need to add `action_listener` to the root BUILD file of
    16  the project.
    17  
    18  ```python
    19  # Extra action invokes /opt/kythe/extractors/bazel_cxx_extractor
    20  extra_action(
    21      name = "extractor",
    22      cmd = ("/opt/kythe/extractors/bazel_cxx_extractor " +
    23             "$(EXTRA_ACTION_FILE) $(output $(ACTION_ID).cxx.kzip) $(location :vnames.json)"),
    24      data = [":vnames.json"],
    25      out_templates = ["$(ACTION_ID).cxx.kzip"],
    26  )
    27  
    28  action_listener(
    29      name = "extract_cxx",
    30      extra_actions = [":extractor"],
    31      mnemonics = ["CppCompile"],
    32      visibility = ["//visibility:public"],
    33  )
    34  ```
    35  
    36  Extractor requires a `vnames.json` file that tells extractor how to translate
    37  certain filepaths. For example in Bazel project java files often stored in
    38  `java` and `javatests` directories. But filepath like
    39  `java/com/some/domain/Foo.java` should be extracted as
    40  `com/some/domain/Foo.java` with the `java` prefix omitted. `vnames.json` file
    41  tells extractor how to rename certain filepaths during extraction. As an example
    42  check `vnames.json` from Kythe repo:
    43  [link](https://github.com/kythe/kythe/blob/master/kythe/data/vnames.json).
    44  
    45  ```shell
    46  cd $YOUR_BAZEL_PROJECT
    47  # As example copy vnames.json from Kythe repo. But you should change it for your project
    48  # later.
    49  curl https://raw.githubusercontent.com/kythe/kythe/master/kythe/data/vnames.json > vnames.json
    50  ```
    51  
    52  Run extractor:
    53  
    54  ```shell
    55  # run on all targets
    56  bazel test --experimental_action_listener=:extract_cxx  //...
    57  
    58  # run on specific target (e.g. some cc_binary)
    59  bazel test --experimental_action_listener=:extract_cxx  //java/some/folder:foo
    60  ```
    61  
    62  Extracted kzip files will be in
    63  `bazel-out/local-fastbuild/extra_actions/extractor` folder. One kzip file per
    64  target.
    65  
    66  ```shell
    67  find -L bazel-out -name '*cxx.kzip'
    68  ```
    69  
    70  #### Development
    71  
    72  Building extractor from sources:
    73  
    74  ```shell
    75  export KYTHE_PROJECT=path/to/kythe/repo/directory
    76  cd $KYTHE_PROJECT
    77  bazel build //kythe/cxx/extractor:cxx_extractor_bazel
    78  ```
    79  
    80  Freshly built extractor will be in folder
    81  `bazel-bin/kythe/cxx/extractor/cxx_extractor_bazel
    82  /opt/kythe/extractors/bazel_cxx_extractor`. Follow instructions of above but
    83  `extra_action` replace `/opt/kythe/extractors/bazel_cxx_extractor` with the path
    84  to the freshly built exractor.