[go: up one dir, main page]
Skip to content

Commit

Permalink
Add code-coverage script, CONTRIBUTING.md
Browse files Browse the repository at this point in the history 
- Add script to run the code-coverage check
- Split the contributing instructions from README.md into
  separate CONTRIBUTING.md.
- Also, include the .md files and the coverage script in the dist tarball.
  • Loading branch information
@cxw42
cxw42 committed Sep 27, 2020
1 parent 80cc37a commit b91d484
Show file tree
Hide file tree
Showing 4 changed files with 123 additions and 86 deletions.
108 changes: 108 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Contributing to pfft

**Note:** Please do not use any code from Stack Overflow. This project uses
under a permissive open-source license, and I would have to change to a
copyleft license if we used code from Stack Overflow.

## Overview

Pfft is written in [Vala](https://wiki.gnome.org/Projects/Vala), which is
a C/C#-like programming language. A good tutorial by naaando starts
[here](https://naaando.gitbooks.io/the-vala-tutorial/content/en/2-first-program/).

Pfft currently only runs on UNIX-like systems. I welcome contributions to
support more platforms! (Please don't change the build system for Linux,
though.) The instructions below are for Ubuntu.

## Building from Git

Tested on Lubuntu Eoan, with additional CI builds on Ubuntu Bionic.

Fork and clone this repo. Then:

1. Install build dependencies, including the version of Vala packaged for your
OS. For example, on Ubuntu:

$ sudo apt install -y build-essential valac valadoc graphviz-dev help2man

2. Install the latest stable version of Vala:

$ git clone https://gitlab.gnome.org/GNOME/vala.git
$ cd vala
$ git checkout 0.48.6 # or whatever the latest stable is
$ ./autogen.sh && make -j4 && sudo make install

3. Install development dependencies for pfft:

$ sudo apt install -y libpango1.0-dev libgee-0.8-dev libgstreamer1.0-dev autotools-dev uncrustify perl lcov

4. In your clone of this repo, initialize submodules:

$ git submodule update --init --recursive

5. Build:

$ ./bootstrap
$ ./configure && make -j4

Note: `libpango1.0-dev` pulls in Pango, Cairo, and pangocairo.

## Testing

`make test` or `make check` at the top level.

In GLib 2.62+, the default output format is TAP. Therefore, you can do
`make build-tests && prove`.

## Checking code coverage

In the top level of the source tree, run `./coverage.sh`. Note
that this will change your configuration (it re-runs `./configure`).
Accordingly, all arguments to `coverage.sh` are passed to `configure`.

Once you have run `coverage.sh`, you can retest without reconfiguring by
running `make -j check-code-coverage`.

Checking coverage will print a summary to the console. For the full report,
open `pfft-coverage/index.html` in a Web browser.

## Making a release

$ make distcheck

This will build `pfft-VERSION.tar.gz` and check it.

## Pull requests

PRs are welcome! I prefer PRs with one commit that adds tests and a subsequent
commit that adds the code (TDD). However, that is not required.

Before submitting a PR, please run `make prep`. This will:

- `make prettyprint` (conform to the coding style)
- `make check` (must pass the tests!)
- `make all build-tests && prove -v` (runs the tests a different way)
- `make distcheck` (make sure the tarball will build)

## Notes on compiling Vala sources

- All the .vala files are run through a single pass of `valac`.
However, the resulting C files are compiled by separate invocations of gcc.
- The valac invocation happens in the _source_ tree. I think this is because
the dist tarball includes the generated C files. Therefore, references
to the generated .h and .vapi files require `$(srcdir)`.
- Even if you `make clean` or `make distclean`, generated .c files will still
be left in the tree. To remove the generated C files,
`make maintainer-clean`.

## Design decisions

- Decisions about the exact appearance of an item should be made as late
as possible. For example, in the `pango-markup` writer (the default),
headers and footers are set in smaller type by the writer, not the upstream
code that feeds markup to the writer.

## Other notes

- All files are UTF-8, no BOM.

2 changes: 2 additions & 0 deletions Makefile.am
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ build-tests:

# Misc.

EXTRA_DIST += README.md CONTRIBUTING.md coverage.sh

prettyprint:
-$(AM_V_GEN)uncrustify -c $(top_srcdir)/.uncrustifyrc --replace \
$(foreach fn, $(MY_all_VALA), $(top_srcdir)/src/$(fn)) \
Expand Down
93 changes: 7 additions & 86 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# PDF From Formatted Text: markdown to PDF with fewer dependencies

[![Build Status](https://travis-ci.org/cxw42/pfft.svg?branch=master)](https://travis-ci.org/cxw42/pfft)
[![codecov](https://codecov.io/gh/cxw42/pfft/branch/master/graph/badge.svg)](https://codecov.io/gh/cxw42/pfft)

I think TeX, LaTeX, and Pandoc are fantastic tools! However, I sometimes
need a markdown-to-PDF converter with fewer dependencies. Pfft is that tool.

Expand All @@ -23,89 +26,9 @@ Pfft:
For the HTML documentation, run `make html`, then open
`doc/valadoc/pfft/index.htm`.

## Hacking on Pfft

All files are UTF-8, no BOM.

### Building from Git

Tested on Lubuntu Eoan, with additional CI builds on Ubuntu Bionic.

Install Vala:

$ sudo apt install -y build-essential valac valadoc graphviz-dev help2man

(NOTE: you may be able to skip this step) Install the latest stable [valac]:

$ git clone https://gitlab.gnome.org/GNOME/vala.git
$ cd vala
$ git checkout 0.48.6 # or whatever the latest stable is
$ ./autogen.sh && make -j4 && sudo make install

Install development dependencies for pfft:

$ sudo apt install -y libpango1.0-dev libgee-0.8-dev libgstreamer1.0-dev autotools-dev uncrustify perl lcov

Initialize submodules:

$ git submodule update --init --recursive

Build:

$ ./bootstrap
$ ./configure && make -j4

Note: `libpango1.0-dev` pulls in Pango, Cairo, and pangocairo.

### Testing
## Contributing to Pfft's development

`make test` or `make check` at the top level.

In GLib 2.62+, the default output format is TAP. Therefore, you can do
`make build-tests && prove`.

### Checking code coverage

./configure --enable-code-coverage && make -j4 check-code-coverage

This will print a summary to the console. For the full report, open
`pfft-<VERSION>-coverage/index.html` in a Web browser.

### Making a release

$ make distcheck

This will build `pfft-VERSION.tar.gz` and check it.

### Pull requests

PRs are welcome! I prefer PRs with one commit that adds tests and a subsequent
commit that adds the code (TDD). However, that is not required.

Before submitting a PR, please run `make prep`. This will:

- `make prettyprint` (conform to the coding style)
- `make check` (must pass the tests!)
- `make all build-tests && prove -v` (runs the tests a different way)
- `make distcheck` (make sure the tarball will build)

### Notes on compiling Vala sources

- All the .vala files are run through a single pass of `valac`.
However, the resulting C files are compiled by separate invocations of gcc.
- The valac invocation happens in the _source_ tree. I think this is because
the dist tarball includes the generated C files. Therefore, references
to the generated .h and .vapi files require `$(srcdir)`.
- Even if you `make clean` or `make distclean`, generated .c files will still
be left in the tree. To remove the generated C files,
`make maintainer-clean`.

### Design decisions

- Decisions about the exact appearance of an item should be made as late
as possible. For example, in the `pango-markup` writer (the default),
headers and footers are set in smaller type by the writer, not the upstream
code that feeds markup to the writer.
See [CONTRIBUTING.md](CONTRIBUTING.md).

## Thanks

Expand All @@ -114,7 +37,5 @@ Before submitting a PR, please run `make prep`. This will:

## Legal

Most of pfft is BSD-3-clause (see file `LICENSE`). The files in `src/logging`
are LGPL 2.1+ (see file `LGPL-2.1`).

[valac]: https://wiki.gnome.org/Projects/Vala
Most of pfft is BSD-3-clause (see file [`LICENSE`](LICENSE)). The files in `src/logging`
are LGPL 2.1+ (see file [`LGPL-2.1`](LGPL-2.1)).
6 changes: 6 additions & 0 deletions coverage.sh
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/bin/bash
set -x
set -eEuo pipefail
./bootstrap
./configure --enable-code-coverage USER_VALAFLAGS='-g' CFLAGS='-g -O0' "$@"
make -j4 check-code-coverage

0 comments on commit b91d484

Please sign in to comment.