Skip to content

Commit

Permalink
Boost->Catch: Final Docs update (#267)
Browse files Browse the repository at this point in the history 
* Updating documentation for the Boost->Catch transition.

* Making suggested grammar improvements.
  • Loading branch information
@arcuru
arcuru committed Apr 20, 2019
1 parent 5a690b4 commit f86a369
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 172 deletions.
16 changes: 4 additions & 12 deletions README.md
View file
Expand Up @@ -13,21 +13,13 @@ There are not many active contributors, so anyone reviewing PRs or Issues, even

## Adding an exercise

Note: We are in the process of transitioning from using the Boost test suite to
Catch, see [#233](https://github.com/exercism/cpp/issues/233). As such, we will
not be taking any new exercises that use the Boost test suite. Please see one
of the exercises that use Catch for examples on how that is setup.

Additionally, any exercises submitted while that work is ongoing will not be a
priority, so may take a while to review.

Here is a list of things that need to be done to add an exercise to this track.

1. Add the exercise under the exercises/ directory.
2. Create your test suite based on the canonical tests in the [problem specifications](https://github.com/exercism/problem-specifications) repo.
3. Create an example solution and name the files 'example.cpp' and 'example.h'.
1. Add the exercise under the `exercises/` directory.
2. Create your test suite based on the canonical tests in the [problem specifications](https://github.com/exercism/problem-specifications) repo, and add a comment at the top of the test suite noting the version of the test suite it implements.
3. Create an example solution and name the files `example.cpp` and `example.h`. `example.cpp` is optional but encouraged.
4. Add the test to the list in the root CMakeLists.txt file.
5. Add the test to the config.json file. The [configlet](https://github.com/exercism/configlet) can help generate a unique UUID.
5. Add the test to the config.json file. The [configlet](https://github.com/exercism/configlet) can help generate a unique UUID. You can download configlet using the script in `bin/fetch-configlet`.
6. Use the [configlet](https://github.com/exercism/configlet) tool to generate the README for your exercise.
7. Try to match the formatting used in the other tests as closely as possible.

Expand Down
163 changes: 43 additions & 120 deletions docs/INSTALLATION.md
View file
Expand Up @@ -4,53 +4,26 @@ The C++ language track requires that you have the following software
installed on your system:
* a modern C++11 compiler
* the CMake cross-platform build system
* the Boost libraries

Microsoft's Visual Studio IDE and Apple's Xcode IDEs combine 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.
We use [Catch2](https://github.com/catchorg/Catch2) for testing, which is a
header-only library that is bundled along with the exercises.

### Prerequisite: A Modern C++11 Compiler
This set of dependencies is very common for C++ projects, so if you have any
issues setting it up you will find many helpful resources online.

Many IDE's, including Microsoft's Visual Studio, Apple's Xcode, and JetBrains'
CLion bundle a compiler and CMake together, so you should only need to install
the IDE.

### A Modern C++11 Compiler

This language track requires a compiler with [C++11](http://en.wikipedia.org/wiki/C%2B%2B11)
support, which was released in 2011. All major compilers released in the last few years should
be compatible, so as long as you are on a fairly recent version you should be fine.
Specifically, GCC version 5.1 or later, Clang version 3.8 or later, or Visual
Studio 2015 or later.

#### Linux

Ubuntu 16.04 and later have compatible compilers in the package manager, so
installing the necessary compiler can be done with `sudo apt-get install gcc`.
If you're on an older version of Ubuntu, you should be able to install a newer
GCC version using the following:

```bash
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
$ sudo apt-get -qq -d update
$ sudo apt-get -qq install g++-5
$ # make g++ 5 the default g++ executable
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-5 90
```

For other distributions, you should be able to acquire the compiler through your
package manager.

#### MacOS

MacOS users can install GCC with [Homebrew](http://brew.sh/) via
`brew install gcc`.

#### Windows

Windows users can get
[Visual Studio Community](https://www.visualstudio.com/vs/community/),
a free download that will give you the Visual Studio IDE and the
latest version of the Microsoft Visual C++ compiler.

### Prerequisite: CMake
### CMake

CMake is an open source cross-platform build system that generates build
scripts for your native build system (`make`, Visual Studio, Xcode, etc.).
Expand All @@ -74,99 +47,49 @@ improve the CMake support.

[CMake 3.1.3 or later](http://www.cmake.org/) is required to use the provided build recipe.

### Prerequisite: Boost 1.59+

**We are in the process of transitioning away from using Boost for most
exercises because it is difficult to install on some platforms. You can
follow the progress, or help, [on Github](https://github.com/exercism/cpp/issues/233).**

The unit tests use Boost.Test, the unit testing framework included with
[Boost](http://www.boost.org/index.html). You may find other libraries
in Boost useful to you as you work through the exercises.
You will need to download and install Boost. As of this writing Boost
1.59+ is the required version. You will need a compiled version of the
boost libraries Boost.Test and Boost.DateTime, or you will need to
download from source and build the library yourself.
## Windows

If you are having difficulties installing Boost for use with exercism,
[ask for help](https://github.com/exercism/cpp/issues).

#### Linux

Linux users can usually get Boost from your distribution's package manager.
If a pre-built package is unavailable for your linux distribution, try
[installing Boost from source](http://www.boost.org/doc/libs/release/more/getting_started/index.html).

Alternately, there may be some other way to install Boost for your
distribution without installing from source. For example, you can install
Boost 1.60 for Ubuntu 16.04 LTS by using a PPA.
Windows users can get
[Visual Studio Community](https://www.visualstudio.com/vs/community/),
a free download that will give you the Visual Studio IDE and the latest version
of the Microsoft Visual C++ compiler.

```
$ sudo add-apt-repository -y ppa:samuel-bachmann/boost
$ sudo apt-get -qq -d update
$ sudo apt-get install boost1.60
```
1. Follow [the instructions here](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio) to setup CMake.
1. Download the exercise using the [exercism cli](https://exercism.io/cli-walkthrough) tool.
1. Open Visual Studio 2017 or higher (With Visual C++ tools for CMake installed as described from the link above).
1. Open the exercise folder in VS.
1. Run "Build->Build the solution". The tests will execute with the build, with the output going to the build window. Since the test runs during the build, VS will say it is a build failure if one of the tests fail, and the test failure messages will be in the build output window.

#### Windows
You should be able to use other integrated IDE's such as JetBrains' CLion in a similar manner.

Windows users can download compiled binaries from [sourceforge](https://sourceforge.net/projects/boost/files/boost-binaries/).
You must download the version appropriate for your compiler. Note that
the version number is different from your Visual Studio version; the
compiler version in Visual Studio 2015 is MSVC 14.0.
## Linux

In the descriptions, 32-bit refers to the kind of code generated by your
compiler and not the operating system. Code compiled for 32-bit will run
on both 32-bit and 64-bit versions of Windows. Code compiled for 64-bit
will only run on 64-bit versions of Windows. The CMake recipes used in
exercism create 32-bit projects for Visual Studio, so download the
appropriate 32-bit version of Boost.
All recent Linux distribution releases have compatible C++11 compilers, you
should be able to install it using your package manager.

Once you download the compiled binaries, install them into a suitable
location. The installed location will contain a libraries directory
named similarly to the install executable, such as `lib32-msvc-12.0`.
Rename this directory to `lib` so that CMake can find the precompiled
libraries. If you don't rename the directory you will see an error
like this when you run CMake:
For example, on Ubuntu you would use the following command to install gcc.

```bash
$ sudo apt-get install gcc
$ gcc --version
```
> cmake -DBOOST_INCLUDEDIR:PATH=D:/tmp/boost_1_59_0 ..
-- Building for: Visual Studio 12
-- The CXX compiler identification is MSVC 18.0.30723.0
-- Check for working CXX compiler using: Visual Studio 12
-- Check for working CXX compiler using: Visual Studio 12 -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
CMake Error at C:/Program Files (x86)/CMake 2.8/share/cmake-2.8/Modules/FindBoost.cmake:1106 (message):
Unable to find the requested Boost libraries.
Boost version: 1.59.0
Boost include path: D:/tmp/boost_1_59_0
The following Boost libraries could not be found:

boost_unit_test_framework
boost_date_time
boost_regex
If you are on an older distribution, you might not have a compiler that
supports C++11. In that case you will need to install it through an alternate
method. For example, Ubuntu 15.10 or earlier don't provide compatible compilers
in the package manager, so if you are using that version you will need to use
the following:

No Boost libraries were found. You may need to set BOOST_LIBRARYDIR to the
directory containing Boost libraries or BOOST_ROOT to the location of
Boost.
Call Stack (most recent call first):
CMakeLists.txt:12 (find_package)
-- Configuring incomplete, errors occurred!
```bash
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
$ sudo apt-get -qq -d update
$ sudo apt-get -qq install g++-5
$ # make g++ 5 the default g++ executable
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-5 90
```

#### MacOS

MacOS users can install boost with [Homebrew](http://brew.sh/) via
`brew install boost`.
## MacOS

#### Building from Source
MacOS users can install GCC with [Homebrew](http://brew.sh/) via
`brew install gcc`.

If all else fails you can download the source and build it yourself,
but you should prefer a prebuilt distribution to make things easier.
Bootstrap instructions are on the
[Boost getting started page](http://www.boost.org/doc/libs/release/more/getting_started/index.html).
48 changes: 8 additions & 40 deletions docs/TESTS.md
View file
Expand Up @@ -5,7 +5,9 @@ console executable that runs the tests. Running the test executable
prints messages for each failing test and reports a non-zero exit status
when tests fail.

*Note:* Your code is being tested against the test suite every time you build your project. If your code does not pass the one or more tests but is valid C++ code, it will still be compiled.
*Note:* Your code is being tested against the test suite every time you build
your project. If your code does not pass the one or more tests but is valid C++
code, it will still be compiled.

Working through each exercise is a process of:

Expand Down Expand Up @@ -44,10 +46,6 @@ your exercise source code, it is common to create a directory called `build`
to hold these generated build files, as well as the compiled code. This
will keep your exercise folder uncluttered and tidy.

Since you will be running CMake to create the build instructions for each
assignment, you might want to create a bash script (Linux/MacOS) or
batch file (Windows) for this command.

Once the build environment has been created by CMake, you can build your
code using the appropriate command for your environment:

Expand Down Expand Up @@ -77,36 +75,12 @@ Simply type `make` in the build directory to compile the tests. This should
generate compile time errors. Once the errors are fixed, `make` will build and
run the tests.

#### Windows with Visual Studio 2017

The generator name for CMake is `Visual Studio 15`. The same generator
supports all IDE editions of Visual Studio 2017: Community, Professional,
and Enterprise. Assuming the current exercise is `bob` and we're in the
exercise folder:

```
> copy nul: bob.h
> copy nul: bob.cpp
> mkdir build
> cd build
> cmake -G "Visual Studio 15" ..
```

This example shows creating empty files for the implementation before
running CMake.
#### Windows with Visual Studio

If you installed boost to the default location, CMake may be able to
find it for you automatically. If it can't find it, you will need to
need to supply additional arguments to tell CMake where to find it by
setting the `BOOST_INCLUDEDIR` variable on the command-line. Here is an
example using the Visual Studio 2017 generator:

```
> cmake -G "Visual Studio 15" -DBOOST_INCLUDEDIR:PATH=D:/Code/boost/boost_1_59_0 ..
```

**Note:** Path locations passed to CMake always use slash (`/`) as the
directory separator, even on Windows.
Visual Studio has native support for CMake projects, so you should not need to
install CMake separately or run it outside of Visual Studio. Follow
[this guide](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio)
to setup the CMake project in Visual Studio.

#### MacOS with Xcode

Expand All @@ -122,9 +96,3 @@ $ cmake -G Xcode ..

This example shows creating empty files for the implementation before
running CMake.

## Boost.Test Documentation

If you need to consult the Boost.Test documentation, you can find it here:

* [Boost.Test 1.59 official documentation](http://www.boost.org/doc/libs/1_59_0/libs/test/doc/html/index.html)

0 comments on commit f86a369

Please sign in to comment.