diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index cf189fe9..7a4f1d91 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -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!