Metadata-Version: 2.1
Name: macgrind
Version: 1.0.3
Summary: A containerized version of Valgrind for OSX.
Home-page: https://github.com/kokkonisd/macgrind
Author: Dimitri Kokkonis
Author-email: kokkonisd@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: docker

# macgrind

![CI](https://github.com/kokkonisd/macgrind/workflows/CI/badge.svg)

Containerized Valgrind on OSX for C and C++ projects.


## why

As of the time of writing this, [Valgrind](https://www.valgrind.org/) is not natively supported on OSX. This tool
allows you to run it in a [Docker](https://www.docker.com/) container without any code changes or extra garbage.


## how to install

You can install `macgrind` via `pip`:

```text
$ pip3 install macgrind
```

You also need to install [Docker Desktop](https://www.docker.com/products/docker-desktop), and have it running.


## how to use

You can use `macgrind` by specifying the project's directory, and a target binary to run `valgrind` on.
Please note that the target binary's path must be the one **relative to the project path** instead of the absolute one.

For example, say I have a C project with the following structure:

```text
my_c_project/
    src/
        main.c
    Makefile
```

I need to supply the full path to `my_c_project/`, but only the relative path to the target executable: `main` (and not
`my_c_project/`). The assumption here is that the `all` target in the `Makefile` builds `my_c_project/main`.

So, we could run `macgrind` like this:

```text
$ macgrind my_c_project/ main
Creating temporary Dockerfile...
Building Docker image...
Running Docker container...
==========
Here's the output of the container:
==1== Memcheck, a memory error detector
==1== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==1== Using Valgrind-3.13.0 and LibVEX; rerun with -h for copyright info
==1== Command: /valgrind_project_tmp/main
==1==
Hello, World!
==1==
==1== HEAP SUMMARY:
==1==     in use at exit: 0 bytes in 0 blocks
==1==   total heap usage: 2 allocs, 2 frees, 4,196 bytes allocated
==1==
==1== All heap blocks were freed -- no leaks are possible
==1==
==1== For counts of detected and suppressed errors, rerun with: -v
==1== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)
Container exited without errors (exit code: 0)
Done!
```

By default, `macgrind` will build a Docker image based on `ubuntu:18.04`. It will then build your project by running
`make all` in the project directory, then run the target using `valgrind --leak-check=full --error-exitcode=1
<target>`.

## more options

You can specify the image on which the container will be built by running `macgrind` with the `-i` (or `--image`)
option:

```text
$ macgrind my_c_project/ main --image ubuntu:16.04
```

Very often, projects depend on additional libraries. You can specify dependencies to be installed with `apt-get` using
the `-d` (or `--dependencies`) option:

```text
$ macgrind my_curl_c_project/ main --dependencies libcurl4-openssl-dev
```

If you wish to run a custom command to build your project or just one target, other than `make all`, you can specify
it using the `-c` (or `--custom-command`) option. Be aware, as with the executable, **the custom command must assume
a relative address, as it will be run inside of your project directory**:

```text
$ macgrind my_c_project/ main --custom-command "gcc src/main.c -o main"
```

To get the full option list, run:

```text
$ macgrind --help
```


