xcode-coveralls is a command line helper tool to upload code coverage data from Xcode projects to coveralls.io.
The xcode-coveralls command needs to be invoked from your repository/project root directory.
Note that if your Xcode project file is in a sub directory, you'll need to specify its path with the --project option.
If you don't use Travis CI, you may also specify a service name and job ID with the --service and --id options.
Builds on Travis CI will automatically detect those values.
You may also use the --token option, if you're not using a service compatible with coveralls.io.
You may also include/exclude specific paths from your sources with the --include and --exclude options.
Those paths may be full paths or paths relative to the repository/project root directory.
The only mandatory argument is the Xcode build directory, containing the .gcda and .gcno files to process.
Please read the following section to learn how to generate those files with Xcode.
In order to use xcode-coveralls, your Xcode targets needs to be configured to produce code coverage data files.
This can be done from a target's build settings.
Two options needs to be activated:
- Generate Test Coverage Files (
GCC_GENERATE_TEST_COVERAGE_FILES) - Instrument Program Flow (
GCC_INSTRUMENT_PROGRAM_FLOW_ARCS)
Although the options are prefixed with GCC, they are completely compatible with Clang/LLVM.
Note that turning those options on will reduce the compilation time, so you might create a specific build configuration for this, and enable it for your unit tests only.
The xcode-coveralls command needs to be invoked with the Xcode build directory, usually in ~/Library/Developer/Xcode/DerivedData/.
The best way to get this directory is to add a Run Script phase in the target for which you want coverage reports:
export | egrep '(BUILT_PRODUCTS_DIR)|(CURRENT_ARCH)|(OBJECT_FILE_DIR_normal)|(SRCROOT)|(OBJROOT)' > xcenv.sh
This will create an xcenv.sh file with the necessary environment variables to find the Xcode build directory.
If using an version control system, you may ignore this specific file.
You may then use this variables in a shell script, in order to invoke xcode-coveralls:
#!/bin/bash
source xcenv.sh
declare -r DIR_BUILD="${OBJECT_FILE_DIR_normal}/${CURRENT_ARCH}/"
xcode-coveralls "${DIR_BUILD}"
Usage: xcode-coveralls [OPTIONS] BUILD_DIRECTORY [BUILD_DIRECTORY ...]
Options:
--help Shows this help dialog
--version Prints the version number
--verbose Turns on extra logging
--gcov Path or command for invoking the gcov utility
(defaults to /usr/bin/gcov)
--include Paths to include from the sources
--exclude Paths to exclude from the sources
--project Path to the Xcode project file, if not at the directory root
--service The service name to use
(defaults to 'travis-ci')
--id The service job ID
(if not specified, defaults to the 'TRAVIS_JOB_ID' environment variable, or zero)
--token The repository token (optional)
--dry-run Do not actually send data to coveralls.io
xcode-coveralls may be installed with Homebrew:
brew install macmade/tap/xcode-coveralls
xcode-coveralls may be installed manually by cloning its GitHub repository and running xcodebuild or xctool.
The default location is /usr/local/bin.
Here's an example with xcodebuild:
git clone https://github.com/macmade/xcode-coveralls.git /tmp/xcode-coveralls
xcodebuild -project /tmp/xcode-coveralls/xcode-coveralls.xcodeproj -scheme xcode-coveralls DSTROOT=/ SYMROOT=build install
And here's an example with xctool:
git clone https://github.com/macmade/xcode-coveralls.git /tmp/xcode-coveralls
sudo xctool --project /tmp/xcode-coveralls/xcode-coveralls.xcodeproj --scheme xcode-coveralls DSTROOT=/ install
Note that you can use this on Travis builds (for instance in before_install) in order to get coverage reports for your project.
xcode-coveralls is released under the terms of the MIT License.
Owner: Jean-David Gadina - XS-Labs
Web: www.xs-labs.com
Blog: www.noxeos.com
Twitter: @macmade
GitHub: github.com/macmade
LinkedIn: ch.linkedin.com/in/macmade/
StackOverflow: stackoverflow.com/users/182676/macmade