Skip to content

Commit 2d13718

Browse files
TomPedTomPed
authored
Update README.md
1 parent 23e3395 commit 2d13718

File tree

1 file changed

+60
-86
lines changed

1 file changed

+60
-86
lines changed

‎README.md

Lines changed: 60 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,11 @@
1-
# Codecov Rust Example [![travisCI](https://travis-ci.org/codecov/example-rust.svg)](https://travis-ci.org/codecov/example-rust) [![codecov.io](http://codecov.io/github/codecov/example-rust/coverage.svg?branch=master)](http://codecov.io/github/codecov/example-rust?branch=master)
2-
3-
| [https://codecov.io][1] | [@codecov][2] | [[email protected]][3] |
4-
| ----------------------- | ------------- | --------------------- |
5-
6-
This repository serves as an **example** of how to use [the Codecov global
7-
uploader][4] with Rust.
8-
9-
Note that the coverage is deliberately incomplete. That
10-
way you can [follow the badge link][5] and see how [Codecov][1]
11-
works. You can view the code there, see hits and misses for coverage, etc.
1+
# [Codecov][1] Rust Example
122

133
**As of July 2, 2016, there is [no option to make rustdoc generate a runnable test executable][7]. That means that documentation tests will not show in your coverage data. If you discover a way to run the doctest executable with kcov, please open an [Issue][8] and we will add that to these instructions.**
144

15-
## Basic Usage
16-
17-
Run your tests with [kcov][6] in order to create the necessary coverage
18-
reports. For example:
19-
20-
```
21-
kcov --exclude-pattern=/.cargo,/usr/lib --verify target/cov target/debug/<PROJECT-NAME>-<hash>
22-
```
23-
24-
`<PROJECT-NAME>` and `<hash>` are the appropriate project name and hash for
25-
your executable.
26-
27-
The hash at the end may change if cargo generates different test
28-
executables with the same name. If you are building your code
29-
differently or without cargo, change the last two arguments
30-
to kcov to respectively represent where you want the coverage to
31-
be stored and which executable to run.
32-
33-
Attempting to run `kcov` with an executable argument ending in a wildcard
34-
like `<PROJECT-NAME>-*` may result in incorrect coverage results as only a
35-
single test executable will run. **For best results, run the kcov command
36-
for each test executable and store the results in separate directories.**
37-
Codecov will automatically find and upload the cobertura.xml files and
38-
merge the coverage for you.
39-
40-
Note that setting the environment variable `RUSTFLAGS="-C link-dead-code"`
41-
during tests build may improve coverage accuracy by preventing dead-code elimination.
42-
Do not set this variable when creating release builds since it will increase
43-
binary size.
44-
45-
After you've run the tests and created a cobertura.xml report, you can
46-
use [the Codecov global uploader][4] to push that report to Codecov.
47-
See below for further details.
48-
49-
Installing `kcov` is largely dependent on your operating system. It is
50-
demonstrated to work on Linux systems but may not be fully compatible with
51-
Windows or OS X. Please lookup the appropriate installation instructions.
52-
The Travis CI example below demonstrates installing `kcov` on a Linux
53-
computer.
54-
55-
The version of `kcov` that is distributed with your package manager may not
56-
work with Rust binaries. You usually need to manually build the latest
57-
master branch and run kcov from there. All of this is taken care of for you
58-
in the `.travis.yml` file below.
59-
60-
## [![travis-org](https://avatars2.githubusercontent.com/u/639823?v=2&s=50)](https://travis-ci.org) Travis CI
61-
62-
### Public Repos
63-
64-
Adjust the following example `.travis.yml` file to test with the versions
65-
of Rust you desire.
5+
## Guide
6+
### Travis Setup
667

8+
Add to your `.travis.yml` file.
679
```yml
6810
language: rust
6911

@@ -108,44 +50,76 @@ after_success: |
10850
bash <(curl -s https://codecov.io/bash) &&
10951
echo "Uploaded code coverage"
11052
```
53+
This will automatically run each executable and store the results in a
54+
different directory. Codecov will automatically find the `cobertura.xml`
55+
files that `kcov` generates and combine the results.
56+
### Produce Coverage Reports
11157

112-
[Codecov][1] is integrated by the following line in `after_success:`.
58+
Run your tests with [kcov][6] in order to create the necessary coverage
59+
reports. For example:
11360

114-
```yml
115-
bash <(curl -s https://codecov.io/bash)
61+
```
62+
kcov --exclude-pattern=/.cargo,/usr/lib --verify target/cov target/debug/<PROJECT-NAME>-<hash>
11663
```
11764

118-
This will automatically run each executable and store the results in a
119-
different directory. Codecov will automatically find the `cobertura.xml`
120-
files that `kcov` generates and combine the results.
65+
`<PROJECT-NAME>` and `<hash>` are the appropriate project name and hash for
66+
your executable.
12167

122-
### Private Repos
68+
The hash at the end may change if cargo generates different test
69+
executables with the same name. If you are building your code
70+
differently or without cargo, change the last two arguments
71+
to kcov to respectively represent where you want the coverage to
72+
be stored and which executable to run.
12373

124-
Add to your `.travis.yml` file.
74+
Attempting to run `kcov` with an executable argument ending in a wildcard
75+
like `<PROJECT-NAME>-*` may result in incorrect coverage results as only a
76+
single test executable will run. **For best results, run the kcov command
77+
for each test executable and store the results in separate directories.**
78+
Codecov will automatically find and upload the cobertura.xml files and
79+
merge the coverage for you.
80+
81+
Note that setting the environment variable `RUSTFLAGS="-C link-dead-code"`
82+
during tests build may improve coverage accuracy by preventing dead-code elimination.
83+
Do not set this variable when creating release builds since it will increase
84+
binary size.
85+
86+
After you've run the tests and created a cobertura.xml report, you can
87+
use [the Codecov global uploader][4] to push that report to Codecov.
88+
See below for further details.
89+
90+
Installing `kcov` is largely dependent on your operating system. It is
91+
demonstrated to work on Linux systems but may not be fully compatible with
92+
Windows or OS X. Please lookup the appropriate installation instructions.
93+
The Travis CI example below demonstrates installing `kcov` on a Linux
94+
computer.
12595

96+
## Caveats
97+
### Private Repos
98+
Add to your `.travis.yml` file.
12699
```yml
127-
env:
128-
global:
129-
- CODECOV_TOKEN=:uuid-repo-token
100+
after_success:
101+
- bash <(curl -s https://codecov.io/bash) -t uuid-repo-token
130102
```
103+
### as `kcov` Version
104+
105+
The version of `kcov` that is distributed with your package manager may not
106+
work with Rust binaries. You usually need to manually build the latest
107+
master branch and run kcov from there. All of this is taken care of for you
108+
in the `.travis.yml` file.
109+
## Support
131110

132-
## Other CI services
111+
### Contact
112+
- Intercom (in-app messanger)
113+
- Email: [[email protected]](mailto:[email protected])
114+
- Slack: [slack.codecov.io](https://slack.codecov.io)
115+
- [gh/codecov/support](https://github.com/codecov/support)
133116

134-
+ Adjust the materials in the above example as necessary for
135-
your CI.
136-
+ Add `CODECOV_TOKEN=<your repo token>` to your CI's environment variables.
137-
(Don't store the raw token in your repo.)
138-
+ Run `bash <(curl -s https://codecov.io/bash)` after tests complete.
117+
1. More documentation at https://docs.codecov.io
118+
2. Configure codecov through the `codecov.yml` https://docs.codecov.io/docs/codecov-yaml
139119

140-
## More details
141120

142-
Visit [the global uploader's repo][4] to view its source and
143-
learn more about the script.
144121

145-
[1]: https://codecov.io
146-
[2]: https://twitter.com/codecov
147-
[3]: mailto:[email protected]
148-
[4]: https://github.com/codecov/codecov-bash
122+
[1]: https://codecov.io/
149123
[5]: http://codecov.io/github/codecov/example-rust?branch=master
150124
[6]: https://simonkagstrom.github.io/kcov/
151125
[7]: http://stackoverflow.com/questions/35547710/does-rustdoc-generate-runnable-binaries

0 commit comments

Comments
 (0)