README.md 4.99 KB
Newer Older
1 2 3 4 5 6 7 8
Table of Contents
=================

- [About this tutorial](#about-this-tutorial)
- [Goal of this tutorial](#goal-of-this-tutorial)
- [How to run it?](#how-to-run-it-)


9
## About this tutorial
GILLES Sebastien's avatar
GILLES Sebastien committed
10

11
This tutorial is heavily inspired from a C++ tutorial created by David Chamont (CNRS) that was given as a lecture with the help of Vincent Rouvreau (Inria) in 2016; latest version of this tutorial used as the basis of current one may be found [there](https://gitlab.inria.fr/FormationCpp/DebuterEnCpp).
GILLES Sebastien's avatar
GILLES Sebastien committed
12

13 14 15 16
Current version provides two major modifications:

* The tutorial is now in english.
* Jupyter notebooks using [Xeus-cling kernel](https://github.com/QuantStack/xeus-cling) are now used, thus enabling a sort of interpreted C++ which is rather helpful for teaching it (even if it is clearly not yet mature...)
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
17

18
I have rewritten entirely and modified heavily several chapters, but the backbone remains heavily indebted to David and Vincent and the TP is still very similar to the original one.
GILLES Sebastien's avatar
GILLES Sebastien committed
19

20 21
As the original tutorial, the present lecture is released under the [Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](http://creativecommons.org/licenses/by-nc-sa/4.0/) licence.

22

23
## Goal of this tutorial
GILLES Sebastien's avatar
GILLES Sebastien committed
24 25 26 27 28 29 30 31 32

This is an introductory lecture to the modern way of programming C++; at the end of it you should:

* Understand the syntax and basic mechanisms of the C++ language in version 14/17.
* Know the different programming styles.
* Know of and be able to use the most useful part of the standard library.
* Be aware of many good programming practices in C++.


33
## How to run it?
GILLES Sebastien's avatar
GILLES Sebastien committed
34

Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
35 36
### Local installation

GILLES Sebastien's avatar
GILLES Sebastien committed
37 38 39 40 41 42
As this tutorial relies heavily on [Xeus-cling kernel](https://github.com/QuantStack/xeus-cling), the only requirement is to install this environment on your machine.

Unfortunately, the support of this kernel is still experimental on Windows; I advise you to use any variant of Linux or macOS (for Windows 10 users you may [install Ubuntu in your Windows session](https://tutorials.ubuntu.com/tutorial/tutorial-ubuntu-on-windows); I haven't tried this myself).

Should the procedure described below not work at some point I invite you to check the link above, but at the time of this writing you need to:

Vicente Mataix Ferrándiz's avatar
Typo  
Vicente Mataix Ferrándiz committed
43
* Install [miniconda3](https://conda.io/miniconda.html) environment (apparently using full-fledged anaconda may lead to conflict in dependencies).
GILLES Sebastien's avatar
GILLES Sebastien committed
44 45 46
* Create a new conda environment and activate it:

```
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
47
conda env create -f environment.yml
48
conda activate training_cpp_2021
GILLES Sebastien's avatar
GILLES Sebastien committed
49 50
```

51 52
Don't forget to activate it each time you intend to run the lecture!

53
**WARNING** At the moment, Conda packaging is broken for the most recent version of macOS (11.3). A [ticket](https://github.com/jupyter-xeus/xeus-cling/issues/403) has been issued and is under work; in the meanwhile use Binder or a local Docker image (see below)
54 55


56
* Then you can run the notebook by going **into its root directory** (or internal links won't work...) in a terminal and typing:
GILLES Sebastien's avatar
GILLES Sebastien committed
57 58

```
59
jupyter lab
GILLES Sebastien's avatar
GILLES Sebastien committed
60 61
```

62
__BEWARE__: I **strongly advise** to use a dedicated environment for the notebook: the ultimate goal is to use a real C++ environment for your project, and the anaconda environment hides the native C++ compiler on your machine.
GILLES Sebastien's avatar
GILLES Sebastien committed
63

64 65

__NOTE__: It is possible to use the notebooks directly from some IDEs like [VSCode](https://gitlab.inria.fr/formations/cpp/gettingstartedwithmoderncpp/-/wikis/home#using-notebooks-with-vscode).
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
66

67
### Docker
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
68

69
It is possible to execute the notebooks in a Docker container by simply typing:
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
70

GILLES Sebastien's avatar
GILLES Sebastien committed
71
````
72
docker run -v $PWD:/home/formation/gettingstartedwithmoderncpp -p 8888:8888 --cap-drop=all registry.gitlab.inria.fr/formations/cpp/gettingstartedwithmoderncpp/xeus-cling:latest
GILLES Sebastien's avatar
GILLES Sebastien committed
73
````
Vicente Mataix Ferrándiz's avatar
Vicente Mataix Ferrándiz committed
74

75 76 77
or 

````
78
docker run -v $PWD:/home/formation/gettingstartedwithmoderncpp -p 8888:8888 --cap-drop=all registry.gitlab.inria.fr/formations/cpp/gettingstartedwithmoderncpp/xeus-cling-and-compilers:latest
GILLES Sebastien's avatar
GILLES Sebastien committed
79
````
80

81 82 83 84 85 86 87 88 89
Few hints for those not familiar with Docker:

* `-v` creates a mapping between local folder and the /home/formation/gettingstartedwithmoderncpp folder in the container; this enables you to edit the file from your comfy local environment and see the file edited this way in the Docker container.
* `--cap-drop=all` is a safety when you're running a Docker image not built by yourself: you're essentially blocking the few remaining operations that might impact your own environment that Docker lets by default open with the run command.
* `-p` gives the port mapping between the Docker image and your local environment.

The lengthy `registry.gitlab.inria.fr/formations/cpp/gettingstartedwithmoderncpp/xeus-cling-and-compilers` is the name of the Docker **image**, if this image is not present locally in your environment Docker will try to fetch it from a *registry* on the Inria Gitlab. 

Then just type [http://localhost:8888/](http://localhost:8888/) in your browser to run the notebooks.
90 91 92 93 94


### BinderHub

A link to a BinderHub instance is given at the top of the project page; foresee few minutes to set up properly the notebooks.
95 96 97 98 99


## For maintainers

Informations related to CI are [here](CI.md).