Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 22 additions & 26 deletions docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,40 +77,36 @@ clang-format -i $(file)

## Exercise anatomy

Each exercise should be contained in a directory `c/exercises/{exercise-name}`.
Each exercise should be contained in a directory `c/exercises/practice/{exercise-name}`.
See [implement-an-exercise-from-specification][] for in depth details on implementing an exercise that matches the specification

The structure of en exercise directory is as follows (note the differing hyphen and underscore usage for directory names and file names respectively):
The structure of an exercise directory is as follows (note the differing hyphen and underscore usage for directory names and file names respectively):

```text
+-- {exercise-name}
+-- makefile
+-- README.md
+-- src
| +-- example.c
| +-- example.h | {exercise_name}.h
+-- test
+-- test_{exercise_name}.c
+-- vendor
+-- unity.c
+-- unity.h
+-- unity_internals.h
+-- {exercise-name}.c
+-- {exercise-name}.h
+-- test_{exercise-name}.c
+-- test-framework
| +-- unity.c
| +-- unity.h
| +-- unity_internals.h
```

* `test` - contains the test file `test_{exercise_name}.c` and a `vendor` directory containing the test harness [Unity][] from [ThrowTheSwitch][].
ThrowTheSwitch has a decent guide on [getting started with Unity][] should you desire a tutorial.
The version of Unity used is indicated in [versions][]. The layout of the test file is described in the [style guide][test-file-layout].
Tests should be written that satisfy `canonical-data.json` file for the exercise in the [problem-specifications][] repository
* `src` - contains the example files `example.c` and `example.h`.
These are both skipped by the `exercism` CLI when downloading to the client, so it is imperative that you do not reference the names of the files in your code.
If you need to provide a header file example that is necessary to run your tests it should be named `{my_exercise}.h` instead.
Please also use [include guards][] in your header files.
The exercise tests can be run using `make` from the repository root.
The top-level makefile will rename the `example.{c|h}` files accordingly (use `make help` to learn about individual targets).
* `makefile` - is the makefile for the exercise as it would build using proper filenames (i.e. `{exercise_name}.c` and `{exercise_name}.h` instead of `example.c` and `example.h` respectively).
Makefiles are expected to change very little between exercises so it should be easy to copy one from another exercise.
* `README.md` - is the readme that relates to the exercise.
These can be generated by the [configlet][] tool from `description.md` for the exercise in the [problem-specifications][] repository, or alternatively a custom one can be written.
`test_{exercise_name}.c` - This file contains all the tests for the exercise.
`test-framework` - directory containing the test harness [Unity][] from [ThrowTheSwitch][].
ThrowTheSwitch has a decent guide on [getting started with Unity][] should you desire a tutorial.
The version of Unity used is indicated in [versions][]. The layout of the test file is described in the [style guide][test-file-layout].
Tests should be written to satisfy `canonical-data.json` file for the exercise in the [problem-specifications][] repository
`{exercise-name}.c` / `{exercise-name}.h` - The exercise's source files.
Please use [include guards][] in your header files.
The exercise tests can be run using `make test` from the repository root.
* `makefile` - is the makefile for the exercise as it would build.
Two rules are required,
test: compile test_{exercise-name}.c and run it.
memcheck: compile test_{exercise-name} with -fsanitize=address, -fno-common, -fno-omit-frame-pointer flag and run it
Makefiles are expected to change very little between exercises so it should be easy to copy one from another exercise.

**Don't forget** to add the exercise to the track's `config.json`. For this you will need to determine the best place to add the exercise within the order of all other track exercises. You will also need to generate a UUID to add here. For both of these tasks you can use the [configlet][] tool; the tool will even lint and format the `config.json` for you after you've made these changes!

Expand Down