From 93fbbaab2a36fb9b99344f0eeb1e6e3a68c3e4c2 Mon Sep 17 00:00:00 2001 From: "yujunzhao@devvm1621.atn0.facebook.com" Date: Tue, 1 Sep 2020 14:56:44 -0700 Subject: [PATCH] Update `README.md` in oss (#43893) Summary: Pull Request resolved: https://github.com/pytorch/pytorch/pull/43893 Update `README.md` in oss, provide more examples, start from the most common use to specified use. Make `README.md` be more friendly and more specific. Test Plan: `README.md` doesn't need test. Reviewed By: malfet, seemethere Differential Revision: D23420203 fbshipit-source-id: 1a4c146393fbcaf2893321e7892740edf5d0c248 --- tools/code_coverage/README.md | 48 ++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/tools/code_coverage/README.md b/tools/code_coverage/README.md index 180ee0b65f1..581c16e65ee 100644 --- a/tools/code_coverage/README.md +++ b/tools/code_coverage/README.md @@ -25,35 +25,49 @@ It’s an integrated tool. You can use this tool to run and generate both file-l * Use different stages like *--run, --export, --summary* to achieve more flexible functionality ## How to use - This part will introduce about the arguments you can use when run this tool. The arguments are powerful, giving you full flexibility to do different work. We have two different compilers, `gcc` and `clang`, and this tool supports both. But it is recommended to use `gcc` because it's much faster and use less disk place. The examples will also be divided to two parts, for `gcc` and `clang`. +## Preparation +The first step is to [build *Pytorch* from source](https://github.com/pytorch/pytorch#from-source) with `CODE_COVERAGE` option `ON`. Besides, you may also want to set `BUILD_TEST` option `ON` to get the test binaries. +See: [how to adjust build options](https://github.com/pytorch/pytorch#adjust-build-options-optional) for reference. Following is one way to adjust build option: +``` +# in build/ folder (all build artifacts must in `build/` folder) +cmake .. -DCODE_COVERAGE=ON -DBUILD_TEST=ON +``` + ## Examples -First step is to set some experimental value if needed: +The default setting is for `gcc`. If you are using `clang`, the first step is to set some environment value if needed: ```bash -# pytorch folder, by default all the c++ binaries are in build/bin/ -export PYTORCH_FOLDER=... -# set compiler type -export COMPILER_TYPE="GCC" or export COMPILER_TYPE="CLANG" -# make sure llvm-cov is available, by default it is /usr/local/opt/llvm/bin +# set compiler type, the default is "GCC" +export COMPILER_TYPE="CLANG" +# set llvm path, by default is /usr/local/opt/llvm/bin export LLVM_TOOL_PATH=... ``` -then command will run all the tests in `build/bin/` and `test/` folder +Great, you are ready to run the code coverage tool for the first time! Start from the simple command: +``` +python oss_coverage.py --run-only=atest +``` +This command will run `atest` binary in `build/bin/` folder and generate reoports over the entire *Pytorch* folder. But you may only be interested in the `aten` folder, in this case, try: +``` +python oss_coverage.py --run-only=atest --interested-only=aten +``` +In *Pytorch*, `c++` tests located in `build/bin/` and `python` tests located in `test/`. If you want to run `python` test, try: +``` +python oss_coverage.py --run-only=test_complex.py +``` + +You may also want to specify more than one test or interested folder, in this case, try: +``` +python oss_coverage.py --run-only=atest c10_logging_test --interested-only aten/src/Aten c10/core +``` +That it is! With these two simple options, you can customize many different functionality according to your need. +By default, the tool will run all tests in `build/bin` folder (by running all executable binaries in it) and `test/` folder (by running `run_test.py`), and then collect coverage over the entire *Pytorch* folder. If this is what you want, try: ```bash python oss_coverage.py ``` -Most times you don't want collect coverage for the entire Pytorch folder, use --interested-folder to report coverage only over the folder you want: -```bash -python oss_coverage.py --interested-folder=aten -``` -Then, still in most cases, if you only run one or several test(s): -```bash -python oss_coverage.py --run-only=atest -python oss_coverage.py --run-only atest basic test_nn.py -``` ### For more complex arguments and functionality *To Be Done*