diff --git a/docs/ABOUT.md b/docs/ABOUT.md index ff7c821ae..31f5cdee1 100644 --- a/docs/ABOUT.md +++ b/docs/ABOUT.md @@ -1,7 +1,9 @@ # About -C is a general purpose language, used for a wide range of applications, from embedded computers to high-performance computing clusters. +C is a general purpose language, used for a wide range of applications, from embedded computers to high-performance computing clusters. -C is commonly found in low level applications as it's a good alternative to harder-to-read assembly languages. It can be compiled to assembly to keep the same level of performance, while increasing readability, and providing a small level of safety with static types! +C is commonly found in low level applications as it's a good alternative to harder-to-read assembly languages. +It can be compiled to assembly to keep the same level of performance, while increasing readability, and providing a small level of safety with static types! -C was created by Dennis Ritchie at Bell Labs, and used to re-implement the Unix operating system. Now, it's one of the most used programming languages, with many compilers supporting providing support for most available hardware and platforms - there's plenty of resources and support available to help you get started! +C was created by Dennis Ritchie at Bell Labs, and used to re-implement the Unix operating system. +Now, it's one of the most used programming languages, with many compilers supporting providing support for most available hardware and platforms - there's plenty of resources and support available to help you get started! diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b2ed97ace..18c62cf0d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,19 +4,19 @@ Thank you for interest in contributing to the Exercism C language track! All contributions are welcome, be it a new exercise, a change to the tooling or documentation, a raised issue or even just a comment on an existing issue or PR. This file provides information to help you get started. -Firstly, have a read of the Exercism [docs repository](https://github.com/exercism/docs), specifically the information on [contributing to a language track](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md), as these documents cover a lot of the basic information. +Firstly, have a read of the [Exercism docs][], specifically the information on [contributing to a language track][], as these documents cover a lot of the basic information. Subsequently note that there are a few things specific to this repository that are explained below. We encourage contributions that provide fixes and improvements to existing exercises. -Please note that this track's exercises must conform to the standards determined in the [problem-specifications](https://github.com/exercism/problem-specifications) repository. +Please note that this track's exercises must conform to the standards determined in the [problem-specifications][] repository. Changes to the tests or documentation of a common exercise will often warrant a pull request in that repository before it can be incorporated into this track's exercises. -If you're unsure, then go ahead and open a GitHub [issue](https://github.com/exercism/c/blob/master/docs/CONTRIBUTING.md#issues), and we'll discuss the change. +If you're unsure, then go ahead and open a GitHub [issue][], and we'll discuss the change. ## Code of Conduct Help us keep Exercism welcoming. -Please read and abide by the [Code of Conduct](https://exercism.io/code-of-conduct). +Please read and abide by the [Code of Conduct][]. ## Git Workflow @@ -29,44 +29,44 @@ Please read and abide by the [Code of Conduct](https://exercism.io/code-of-condu ## Issues -We keep track of bugs, enhancements and support requests in the repository using GitHub [issues](https://github.com/exercism/c/issues). +We keep track of bugs, enhancements and support requests in the repository using GitHub [issues][]. -For higher-level discussions about the project as a whole, check out the issues in the [discussions](https://github.com/exercism/discussions/issues) repository. +For higher-level discussions about the project as a whole, check out the issues in the [discussions][] repository. ### Good First Patch -We're trying to label issues with "good first patch" if we think that these can be solved without too much context about Exercism's codebase or functionality. To find them, you can do a [search](https://github.com/exercism/c/good-first-patch). +We're trying to label issues with "good first patch" if we think that these can be solved without too much context about Exercism's codebase or functionality. To find them, you can do a search for [good-first-patch][]. ## Pull Requests -It would be awesome if you follow these [simple guidelines](https://github.com/exercism/docs/blob/master/contributing/pull-request-guidelines.md) while creating your PR, but it isn't required. +It would be awesome if you follow these simple [pull request guidelines][] while creating your PR, but it isn't required. Pull requests should be focused on a single, issue or change. We welcome changes to code style and wording but please open a separate PR for these changes if possible. Please open an issue before creating a PR that makes significant (breaking) changes to an existing exercise or makes changes across many exercises. It is best to discuss these changes before doing the work. -If your change is to an exercise you can run the CI scripts before submitting the pull request, or they will be automatically run after, as described in [Continuous Integration & Tests](https://github.com/exercism/c/blob/master/docs/CONTRIBUTING.md#continuous-integration--tests) +If your change is to an exercise you can run the CI scripts before submitting the pull request, or they will be automatically run after, as described in [Continuous Integration][]. When submitting a pull request, sometimes we will ask you to make changes before we accept the patch. Please do not close the first pull request and open a second one with these changes. If you push more commits to a branch that you've opened a pull request for, it automatically updates the pull request. -If you want to create a PR with changes that aren't quite ready to be merged to master yet (maybe you would like to discuss some particular item, for example), create the PR as normal but add `[WIP]` to the title so that maintainers know that it isn't quite ready to be merged just yet. +If you want to create a PR with changes that aren't quite ready to be merged to master yet (maybe you would like to discuss some particular item, for example), create the PR as normal but use the GitHub website interface to [convert the PR to a draft][] so that maintainers know that it isn't quite ready to be merged just yet. As with adding more commits, you do not need to close your pull request and open a new one if you change the history (rebase, squash, amend), and use git push --force to update the branch on your fork. The pull request points to that branch, not to specific commits. ## Coding Style -The code style expected for code change contributions is explained in the [style guide](https://github.com/exercism/c/blob/master/docs/C_STYLE_GUIDE.md). +The code style expected for code change contributions is explained in the [style guide][]. -The exercise code is checked during [CI](https://github.com/exercism/c/blob/master/docs/CONTRIBUTING.md#continuous-integration--tests) for conformance to the spacing and indentation style rules. +The exercise code is checked during [CI][Continuous Integration] for conformance to the spacing and indentation style rules. The check uses the GNU `indent` CLI tool. When adding or making a change to an exercise, you can check that your change conforms to these rules by running the tool locally before committing. On Linux `indent` should be available for install via your distribution's package manager. -On a Mac you can install the package `gnu-indent` using [Homebrew](https://brew.sh). +On a Mac you can install the package `gnu-indent` using [Homebrew][]. Indent can be run on all files by executing `indent.sh`. To manually run it on a single file, you can execute: @@ -83,55 +83,90 @@ indent -nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0 -d0 -d ## Exercise anatomy -Each exercise should be contained in a directory `c/exercises/` with `` referring to the name of the exercise. -See [implement-an-exercise-from-specification](https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md) for in depth details on implementing an exercise that matches the specification +Each exercise should be contained in a directory `c/exercises/{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's directory is as follows (note the differing hyphen and underscore usage for directory names and file names respectively): +The structure of en exercise directory is as follows (note the differing hyphen and underscore usage for directory names and file names respectively): -``` -+-- +
++-- {exercise-name}
     +-- makefile
     +-- README.md
     +-- src
     |   +-- example.c
-    |   +-- example.h | .h
+    |   +-- example.h | {exercise_name}.h
     +-- test
-        +-- test_.c
+        +-- test_{exercise_name}.c
         +-- vendor
             +-- unity.c
             +-- unity.h
             +-- unity_internals.h
-```
+
-* `test` - contains the test file `test_.c` and a `vendor` directory containing the test harness [Unity](http://www.throwtheswitch.org/unity/) from [ThrowTheSwitch](http://www.throwtheswitch.org/#intro-1-section). -ThrowTheSwitch has a decent guide on [getting started with Unity](http://www.throwtheswitch.org/getting-started-with-unity/) should you desire a tutorial. The version of Unity used is indicated in [versions](https://www.github.com/exercism/c/blob/master/docs/VERSIONS.md). The layout of the test file is described in the [style guide](https://github.com/exercism/c/blob/master/docs/C_STYLE_GUIDE.md#test-file-layout). Tests should be written that satisfy the exercise's related `canonical-data.json` file in the [`problem-specifications`](https://github.com/exercism/problem-specifications) repository +* `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 the [`bin/run-tests`][run-tests] script which will rename the `example.{c|h}` files accordingly. +* `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. -* `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 `.h` instead. -Please also use [`include`](http://faculty.cs.niu.edu/~mcmahon/CS241/c241man/node90.html) guards in your header files. -The [tests](https://github.com/exercism/c/blob/master/docs/CONTRIBUTING.md#what-are-the-ci-scripts) can be run using the [`bin/run-tests`](https://github.com/exercism/c/blob/master/bin/run-tests) script which will rename the `example.{c|h}` files accordingly. +**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! -* `makefile` - is the makefile for the exercise as it would build using proper filenames (i.e. `.c` and `.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 and adjust the filenames therein. +FYI - to get the install artifact for the configlet tool, checkout the [configlet releases page][]. -* `README.md` - is the readme that relates to the exercise. These can be generated by the [configlet](https://github.com/exercism/configlet#configlet) tool from the exercise's related `description.md` in the [`problem-specifications`](https://github.com/exercism/problem-specifications) repository, or alternatively a custom one can be written. +## Continuous Integration -**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](https://github.com/exercism/configlet#configlet) tool; the tool will even lint and format the `config.json` for you after you've made these changes! +This repository uses GitHub workflows to run some tools on each commit to a pull request. +The simplest way to run these workflows on your own contribution is to open a PR on this repository with your changes, set the PR as a draft, then allow this repository's CI setup to take care of things for you automatically. -FYI - to get the install artifact for the configlet tool, checkout the configlet repository's [releases page](https://github.com/exercism/configlet/releases) +### CI environment -## Continuous Integration & Tests +GitHub runs the CI on virtual machines it refers to as [hosted runners][]. +Workflows can configure some aspects of the runners they would like to be run on. -The repository uses Travis CI to run some scripts on each commit to a pull request. -The simplest way to run these scripts on your own contribution is to open a PR on this repository with your changes, edit the PR title to add `[WIP]` then allow this repository's CI setup to take care of things for you automatically. +The workflows in this repository specify only that they each should be run on Ubuntu 18.04. +The later LTS version of Ubuntu (20.04) is specifically not used due to ongoing work by GitHub on the virtual machines. +This work means that specifying `latest`, for example, is not guaranteed to result in 20.04 machine, but could result in an 18.04 one. +As some of the tools (namely `indent`) perform differently on different these different OS versions, the maintainers of this repo have taken the decision to stay with 18.04 until GitHub have completed their work (see [actions/virtual-environments#1816][] for information on progress). ### Run CI on Your Own Fork -If you would like, it is also possible to run Travis on your own fork. -The good folks at fish-shell have [some great information](https://github.com/fish-shell/fish-shell/blob/master/CONTRIBUTING.md#travis-ci-build-and-test) to help you get started with setting up Travis on your own fork. +If you would like, it is also possible to run the CI on your own fork, simply clone this repository as normal on GitHub. +The YAML files located in [`./.github/workflows/`][workflows] should work just the same. +If you would like the [`/format`][format-workflow] automated action to work correctly, you will need to add a deploy key to your cloned repository. + +### The Workflows + +* `checks.yml` runs `shellcheck` on the tool scripts and subsequently runs the following of those tools: + * `./bin/verify-indent` + * `./bin/check-unitybegin` + * `./bin/verify-unity-version` +* `configlet.yml` fetches the latest version of configlet from which it then runs the `lint` command on the track +* `format-code.yml` checks for the string `/format` within any comment on a PR, if it finds it then `indent` is run on the exercises and any resulting changes are committed. A deploy key is required for the commit to be able to re-trigger CI. The deploy key is administered by Exercism directly. +* `build.yml` runs the `./bin/run-tests` tool on all exercises + +### The Tools + +You can see from the [workflows][] that GitHub is instructed to run tools from the [`./bin`][bin] directory. +The work the tools in this directory perform is described as follows: -### Run CI Scripts Locally -You can also run individual scripts on your own machine before committing. -Firstly make sure you have the necessary tools installed (such as `indent`, [`git`](https://git-scm.com/), [`sed`](https://www.gnu.org/software/sed/manual/sed.html), [`make`](https://www.gnu.org/software/make/) and a C compiler), and then run the required script from the repository root. For example: +* `check-unitybegin` ensures that every test file correctly adds the `UnityBegin("{test-file-name}")` line at the start of its `main()` function. +* `fetch-configlet` fetches the `configlet` tool from its [repository][configlet]. +* `verify-indent` runs the `indent` tool and verifies that it did not result in any file changes. +* `verify-unity-version` checks the version of the Unity test framework used by every exercise. The version this file should check for is specified in [`./docs/VERSIONS.md`][versions] +* `run-tests` loops through each exercise, prepares the exercise for building and then builds it using `make`, runs the unit tests and then checks it for memory leaks with AddressSanitizer. + +### Run Tools Locally + +You can also run individual tools on your own machine before committing. +Firstly make sure you have the necessary applications installed (such as `indent`, [`git`][git], [`sed`][sed], [`make`][make] and a C compiler), and then run the required tool from the repository root. For example: ```bash ~/git/c$ ./bin/run-tests @@ -143,17 +178,34 @@ If you'd like to run only some of the tests to check your work, you can specify ~/git/c$ ./bin/run-tests acronym all-your-base allergies ``` -### What Are the CI Scripts? -You can see from the [.travis.yml](https://github.com/exercism/c/blob/master/.travis.yml) file that Travis is instructed to run scripts from the [`./bin`](https://github.com/exercism/c/tree/master/bin) directory. -The work these scripts perform is described as follows: - -- `fetch-configlet` just fetches the `configlet` tool from its [repository](https://github.com/exercism/configlet). - -- `configlet` is a tool, specific to Exercism, that performs some repository management tasks. -The command for `configlet` used by Travis is [`lint`](https://github.com/exercism/configlet/blob/master/README.md#lint). If `configlet` finds any issues Travis will output the details and report a failure on the related PR. - -- `verify-indent` runs `indent` and verifies that it did not result in any file changes. -If the check does result in file changes, Travis will output the details and report a failure on the related PR. - -- `run-tests` loops through each exercise, prepares the exercise for building and then builds it using `make`, runs the unit tests and then checks it for memory leaks with AddressSanitizer. -If there are build errors, any test fails or there is a memory leak, Travis will output the details and report a failure on the related PR. +[Exercism docs]: https://github.com/exercism/docs +[contributing to a language track]: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md +[problem-specifications]: https://github.com/exercism/problem-specifications +[issue]: ./CONTRIBUTING.md#issues +[Code of Conduct]: https://exercism.io/code-of-conduct +[issues]: https://github.com/exercism/c/issues +[discussions]: https://github.com/exercism/discussions/issues +[good-first-patch]: https://github.com/exercism/c/good-first-patch +[pull request guidelines]: https://github.com/exercism/docs/blob/master/contributing/pull-request-guidelines.md +[Continuous Integration]: ./CONTRIBUTING.md#continuous-integration +[convert the PR to a draft]: https://github.blog/changelog/2020-04-08-convert-pull-request-to-draft/ +[style guide]: ./C_STYLE_GUIDE.md +[Homebrew]: https://brew.sh +[implement-an-exercise-from-specification]: https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md +[Unity]: http://www.throwtheswitch.org/unity/ +[ThrowTheSwitch]: http://www.throwtheswitch.org/#intro-1-section +[getting started with unity]: http://www.throwtheswitch.org/getting-started-with-unity/ +[versions]: ./VERSIONS.md +[test-file-layout]: ./C_STYLE_GUIDE.md#test-file-layout +[include guards]: http://faculty.cs.niu.edu/~mcmahon/CS241/c241man/node90.html +[run-tests]: ../bin/run-tests +[configlet]: https://github.com/exercism/configlet +[configlet releases page]: https://github.com/exercism/configlet/releases +[hosted runners]: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners +[actions/virtual-environments#1816]: https://github.com/actions/virtual-environments/issues/1816 +[workflows]: ../.github/workflows/ +[bin]: ../bin +[format-workflow]: ../.github/workflows/format-code.yml +[git]: https://git-scm.com/ +[sed]: https://www.gnu.org/software/sed/manual/sed.html +[make]: https://www.gnu.org/software/make/ diff --git a/docs/C_STYLE_GUIDE.md b/docs/C_STYLE_GUIDE.md index 778667375..a942eecd8 100644 --- a/docs/C_STYLE_GUIDE.md +++ b/docs/C_STYLE_GUIDE.md @@ -2,11 +2,12 @@ This guide describes the style intended for use with the C track exercise example and test files. -The rules within this guide are in addition to, or to call out, those in the [Linux kernel coding style guide](https://www.kernel.org/doc/html/latest/process/coding-style.html). +The rules within this guide are in addition to, or to call out, those in the [Linux kernel coding style guide][]. ## C Standard -Code should conform to the C99 standard, more formally known as ISO/IEC 9899:1999. POSIX, or otherwise non-standard library functions, types or other references that are external to the implementation should not be used. +Code should conform to the C99 standard, more formally known as ISO/IEC 9899:1999. +POSIX, or otherwise non-standard library functions, types or other references that are external to the implementation should not be used. ## Names @@ -54,22 +55,24 @@ While aware that POSIX reserves the `_t` suffix, the track does not currently ut ## Parameters -Function parameters should be named in both the declaration and definition of all functions. This applies to both `.c` and `.h` files. +Function parameters should be named in both the declaration and definition of all functions. +This applies to both `.c` and `.h` files. The names used should match in all instances. That is to say that while the following function prototype is valid C, the style is incorrect because the parameter is unnamed: `void foo(int);`. The correct prototype, providing that all other declarations and the definition also use the parameter name `bar`, would be `void foo(int bar);`. -Where it is simpler or more appropriate to do so, parameters that require passing arguments by value rather than by pointer are preferred. Note especially that this includes `struct` type parameters. +Where it is simpler or more appropriate to do so, parameters that require passing arguments by value rather than by pointer are preferred. +Note especially that this includes `struct` type parameters. In the case that a student is not expected to change the values of a pointer-type parameter within their implementation, that parameter should be `const` qualified. ## Indentation and Format -The repository uses the `indent` tool, as outlined in the [contributing guide](https://github.com/exercism/c/blob/master/docs/CONTRIBUTING.md). +The repository uses the `indent` tool, as outlined in the [contributing guide][]. -The options described for use with indent there are `-linux -i3 -nut`. The `-linux` option is a shortcut that is equivelent to a secific fixed group of options. The combined equivalent options are `-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0 -d0 -di1 -nfc1 -i3 -nut -ip0 -l80 -lp -npcs -nprs -npsl -sai -saf -saw -ncs -nsc -sob -nfca -cp33 -ss -il1`. +The options described for use with indent there are `-linux -i3 -nut`. The `-linux` option is a shortcut that is equivalent to a specific fixed group of options. The combined equivalent options are `-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0 -d0 -di1 -nfc1 -i3 -nut -ip0 -l80 -lp -npcs -nprs -npsl -sai -saf -saw -ncs -nsc -sob -nfca -cp33 -ss -il1`. -What these options do is indicated by the [GNU `indent` manual](https://www.gnu.org/software/indent/manual/indent.html#SEC4), but is also described here for easy reference if editing files manually. +What these options do is indicated by the [GNU `indent` manual][indent-manual], but is also described here for easy reference if editing files manually. - `nbad` - Do _not_ force blank lines after every block of declarations - `bap` - Force a black line after every function body @@ -107,7 +110,7 @@ What these options do is indicated by the [GNU `indent` manual](https://www.gnu. ## Test file layout -Each exercise's test file follows a particular layout. +the test file of each exercise follows a particular layout. The layout is intended to both help contributors to identify parts of the file, and to help learners to understand how the tests work. Like most C source files, a test file begins with includes. @@ -138,6 +141,7 @@ Next are the test functions themselves. The names of these functions use a `test_` prefix. Excepting the first, each test function should have `TEST_IGNORE();` as its first statement. The first occurrence of this should be followed by the line comment `// delete this line to run test`. + For example: ```c @@ -177,3 +181,7 @@ int main(void) return 0; } ``` + +[Linux kernel coding style guide]: https://www.kernel.org/doc/html/latest/process/coding-style.html +[contributing guide]: ./CONTRIBUTING.md +[indent-manual]: https://www.gnu.org/software/indent/manual/indent.html#SEC4 diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index e4b2c6f42..50c5a576c 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -6,29 +6,26 @@ on your system: * A modern C compiler * The Make build tool -Apple's Xcode IDE combines the compiler and -the native build system into a single IDE (integrated development -environment). Linux environments typically expose the compiler and native -build system as separate command-line tools. - +Apple's Xcode IDE combines the compiler and the native build system into a single IDE (integrated development environment). +Linux environments typically expose the compiler and native build system as separate command-line tools. ## Linux -Linux users will need gcc or clang for the compiler, and `make` will be needed -for the native build. Make is pre-installed on most unix systems, but is most -likely available via your package manager. On Debian and Ubuntu based -distributions everything you need can be installed with `sudo apt-get install build-essential` -if not present. - +Linux users will need gcc or clang for the compiler, and `make` will be needed for the native build. +Make is pre-installed on most unix systems, but is most likely available via your package manager. +On Debian and Ubuntu based distributions everything you need can be installed with `sudo apt-get install build-essential` if not present. ## MacOS -MacOS users can install gcc or clang with [Homebrew](http://brew.sh/) via -`brew install gcc` or `brew install llvm`. - +MacOS users can install gcc or clang with [Homebrew][]] via `brew install gcc` or `brew install llvm`. ## Windows -Windows 10 users are recommended to use [WSL Bash](https://msdn.microsoft.com/en-us/commandline/wsl/about), and proceed with the instruction for linux above. +Windows 10 users are recommended to use the [Windows Subsystem for Linux][], and proceed with the instruction for linux above. + +If you are using an earlier version of Windows or WSL Bash is not available to you, you could use [MSYS][] or or [mingw-w64][]. -If you are using an earlier version of Windows or WSL Bash is not available to you, you could use [MSYS/MinGW](http://www.mingw.org/) (32-bit only) or [mingw6-w64](http://mingw-w64.org/doku.php) (32 & 64-bit). +[Homebrew]: https://brew.sh +[Windows Subsystem for Linux]: https://msdn.microsoft.com/en-us/commandline/wsl/about +[MSYS]: https://www.msys2.org/ +[mingw-w64]: http://mingw-w64.org/doku.php diff --git a/docs/LEARNING.md b/docs/LEARNING.md index 226adfd36..3a5517783 100644 --- a/docs/LEARNING.md +++ b/docs/LEARNING.md @@ -2,35 +2,33 @@ ## Learning C From Ground Zero -In general, exercism assumes you already know the syntax and mechanisms -of a language in a particular track. However, knowing the syntax of a -language is merely the first step in gaining expertise in a language. -Exercism allows you to practice solving problems and share discussion -with other programmers who have solved the same problem. It is from -the shared discussion that we gain expertise and insight into becoming -better programmers. - -If you are brand new to the C language, you should spend time learning -the basics of the language first. Here are a few resources that can -help you get started: - -* [Learn C](http://www.learn-c.org/) -* [CS50x](https://www.edx.org/course/introduction-computer-science-harvardx-cs50x) - -[CodeChef](https://www.codechef.com/ide) is a simple web form -interface to a C compiler that will let you try out small programs. -Sometimes this can be an easier way to perform a quick experiment than -building something locally in an integrated development environment. +In general, Exercism assumes you already know the syntax and mechanisms of a language in a particular track. +However, knowing the syntax of a language is merely the first step in gaining expertise in a language. +Exercism allows you to practice solving problems and share discussion with other programmers who have solved the same problem. +It is from the shared discussion that we gain expertise and insight into becoming better programmers. + +If you are brand new to the C language, you should spend time learning the basics of the language first. +Here are a few resources that can help you get started: + +* [Learn C][] +* [CS50x][] + +[CodeChef][] is a simple web form interface to a C compiler that will let you try out small programs. +Sometimes this can be an easier way to perform a quick experiment than building something locally in an integrated development environment. ## Test-Driven Development in C -Exercism assumes that you are familiar with the concept of test-driven -development. Each exercise comes with a series of tests that are already -written for you. You progress through the exercise one test at a time, -writing an implementation incrementally to satisfy the tests. +Exercism assumes that you are familiar with the concept of test-driven development. +Each exercise comes with a series of tests that are already written for you. +You progress through the exercise one test at a time, writing an implementation incrementally to satisfy the tests. + +If you are new to test-driven development, it is strongly recommended that you first work through a [quick overview of some test frameworks for C][test-frameworks] or read the book [Test-Driven Development for Embedded C][tdd] by James Grenning. +These resources cover [Unity][] and [CppUTest][]; this track uses Unity. -If you are new to test-driven development, it is strongly recommended -that you first work through a [quick overview of some test frameworks for C](http://www.drdobbs.com/testing/unit-testing-in-c-tools-and-conventions/240156344) -or read the book [Test-Driven Development for Embedded C](https://pragprog.com/book/jgade/test-driven-development-for-embedded-c) -by James Grenning. These resources cover [Unity](http://www.throwtheswitch.org/unity/) - and [CppUTest](http://cpputest.github.io/); this track uses Unity. +[Learn C]: https://www.learn-c.org/ +[CCS50x]: https://www.edx.org/course/cs50s-introduction-to-computer-science +[CodeChef]: https://www.codechef.com/ide +[test-frameworks]: https://www.drdobbs.com/testing/unit-testing-in-c-tools-and-conventions/240156344 +[tdd]: https://pragprog.com/book/jgade/test-driven-development-for-embedded-c +[Unity]: https://www.throwtheswitch.org/unity/ +[CppUTest]: https://cpputest.github.io/ diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index a87b4eb66..a79cb5580 100644 --- a/docs/RESOURCES.md +++ b/docs/RESOURCES.md @@ -1,4 +1,5 @@ # Resources -- [C++ Reference](http://en.cppreference.com/w/): An online reference for C and C++ programming languages. You have a doubt what a method does? cppreference.com has you covered. -- [`C` tag on StackOverflow](http://stackoverflow.com/questions/tagged/c) +- [C++ Reference](https://en.cppreference.com/w/c): An online reference for C and C++ programming languages. + If you are not sure what a stdlib function does, this site has you covered. +- [`C` tag on StackOverflow](https://stackoverflow.com/questions/tagged/c) diff --git a/docs/TESTS.md b/docs/TESTS.md index d43c673c3..04a47118d 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -7,6 +7,7 @@ Each test file is meant to link against your implementation to provide a console Running the test executable prints messages for each failing test and reports a non-zero exit status when tests fail. To work through an exercise: + * Create the initial build with Make * For each unit test: * Remove the `TEST_IGNORE()` line. @@ -24,39 +25,39 @@ For instance, the exercise `bob` expects an implementation in `src/bob.h` and `s For exercises with dashes in their name, the source files are assumed to use underscores, so `word-count` expects `src/word_count.h` and `src/word_count.c`. You may decide that your implementation is sufficiently simple that it can live entirely in the header, in which case you can omit the `c` file. -**Create your initial implementation files before running Make.** +**Create your initial implementation files before running Make.** If you do not have files `src/bob.h` and `src/bob.c` when running Make for exercise `bob`, then Make will generate an error about files not being found. **These files can be empty, but they must exist.** ### Build your code The simplest way to build your code is by using `make` at the command line (CLI). -On Linux the CLI is available in bash or similar, on MacOS use Terminal. +On Linux the CLI is available in bash or similar, on MacOS use Terminal. On Windows 10, the Windows Subsystem for Linux (WSL) Bash is available. -To do this, assuming we're in the exercise folder: +To do this, assuming the current directory is the exercise folder: ```bash -$ make +make ``` This will compile your code, and run the tests. -The `makefile` comes also with a build that checks some common mistakes regarding memory leaks and out of bound access to arrays. To run these checks, simply run: -``` -$ make memcheck +The `makefile` comes also with a build that checks some common mistakes regarding memory leaks and out of bound access to arrays. To run these checks, use the following at the command line: + +```bash +make memcheck ``` -from the command line. ### Clean up To clean up after a build, you can tell `make` to delete all of the build output, including the executable: ```bash -$ make clean +make clean ``` #### MacOS Build Alternative -On MacOS you can also use Xcode. -To build the code select _Build_ from the toolbar. +On MacOS you can also use Xcode. +To build the code select _Build_ from the toolbar. diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index 6eee8b00d..1a531d5b9 100644 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -1,3 +1,3 @@ # Versions -- Unity = v2.5.2 (version now specified in `unity.h`) \ No newline at end of file +* Unity = v2.5.2 (version now specified in `unity.h`)