Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 5c32e57a authored by GILLES Sebastien's avatar GILLES Sebastien
Browse files

#101 Update the notebook part of 0b notebook to account for the change from Xeus cling to Cppyy.

parent 8ab7b052
Branches
No related tags found
1 merge request!114Use CppyyKernel to run the notebooks instead of Xeus-cling.
Hide whitespace changes
Inline Side-by-side
0b-getting_started_with_tutorial.ipynb
+ 49
− 18
View file @ 5c32e57a
%% Cell type:markdown id: tags:
# [Getting started in C++](./) - [Getting started with the tutorial](./getting_started_with_tutorial.ipynb)
%% Cell type:markdown id: tags:
## About the choice of a Jupyter notebook
## Jupyter notebook
This notebook uses up [xeus-cling](https://xeus-cling.readthedocs.io/en/latest/), a special instance of Jupyter able to run C++ code based upon xeus (tool to build Jupyter kernels for any language) and cling (a creation from CERN to be able to run C++ as an interpreted language).
### About the choice of a Jupyter notebook
The reasons for these choices is to really access directly to handle C++ code without the hassle of explaining how to compile and run stuff, which is an especially cumbersome way to start with this (or any really...) language.
We made the choice to use a Jupyter notebook for conveniency:
This is not to say this tutorial will ignore entirely these topics (see the dedicated [chapter](./6-InRealEnvironment/0-main.ipynb)), just that we will first focus on C++ code. However keep in mind that this notebook's fancy interpreter is not a typical C++ environment.
- We can delve directly into the syntax of the language itself, without muddying the water with peripherical stuff such as explaining from the beginning how a build system works.
(don't worry we'll cover real environments [in part 6](./6-InRealEnvironment/0-main.ipynb)
- Notebooks are a cool tool to meddle explanations and actual code that is directly executable.
## When the notebook is not enough...
However, Jupyter notebooks were clearly not initially designed with C++ in mind (Jupyter stands for **Ju**Lia **Py**thon and **R** - these three langages are either interpreted or just-in-time, whereas C++ is a compiled langage).
As we shall see repeatedly, Xeus-cling notebooks are far from being full-proof: some stuff that are perfectly acceptable C++ aren't accepted in them, and some others required work-arounds. When such an issue appears:
This didn't stop people from trying, leveraging the [cling](https://root.cern/cling) project from CERN which aims to provide an interpreter to the C++ langage.
* It will be indicated explicitly in the notebook if a specific work around is used. We do not want you to take Jupyter work-arounds as a legit advice on how to write proper C++.
* If Jupyter can't deal with the code, we will use [Coliru](https://coliru.stacked-crooked.com/). Coliru is a C++ online compiler; others are listed [here]([GitHub page](https://arnemertz.github.io/online-compilers/)) ([Wandbox](https://wandbox.org/) deserves a shout out as it enables testing the same code with a great variety of compiler versions).
Up to summer 2024, we were using [Xeus-cling](https://xeus-cling.readthedocs.io/en/latest) to run this tutorial; however this project was stagnating and in particular doesn't seem keen to adopt C++ 20, which is (partially) supported by the cling interpreter.
We're not sure we'll keep using Jupyter notebooks in the future: development of Xeus-cling has a bit stalled in the recent years and support of more recent versions of C++ (20 and more) is still unclear.
We have therefore switched to a [homemade Jupyter kernel](https://gitlab.inria.fr/sed-saclay/cppyy_kernel) which uses up the fantastic [cppyy](https://cppyy.readthedocs.io) project, which enables running C++ code from a Python environment.
That being said, it is important to keep in mind that this notebook's fancy interpreter is absolutely not a typical C++ environment.
### When cling / the notebook is not enough...
Even if notebooks are really useful, there are some C++ operations that are not fully supported, be it due to cling limitations (either intrinsic or just because some new C++ features aren't yet covered) or to the way we implemented our kernel around cppyy.
We try our best to make the most content available directly, and we designed our kernel accordingly. We used so-called *magics* to do so, so don't be surprised if some cells starts with a line such as:
```jupyter
%%cpptoolbox cppyy/cppdef
```
Such lines are dedicated to the running of the tutorial and have nothing to do with C++ itself; you may entirely ignore it (unless of course you intend to use our cppyy kernel for your own purposes).
The most common such magics are:
- `%%cpptoolbox cppyy/cppdef`: cppyy in fact defines two different functions `cppexec` and `cppdef`. The former is for code deemed to be executed, the latter for code that defines classes, functions and so on. In our Jupyter kernel we use by default `cppexec`, which works just fine for most operations. However some really need to call under the hood `cppdef`, and that's the reason for this magics.
- `%%cpptoolbox clang`: this magics tells that the entire content of the cell is to be written into a file that is to be compiled by `clang++` compiler; the executable hence produced is then run directly and its output is printed in the notebook. Contrary to the usual behaviour, the content of the cell is sandboxed and self-contained.
The list of all magics may be displayed with following cell:
%% Cell type:code id: tags:
``` c++
%%cpptoolbox
;
```
%% Cell type:markdown id: tags:
## Few guidelines about Jupyter
### Few guidelines about Jupyter
You might not be familiar with Jupyter notebooks, so here are few tips to run it smoothly (the _Help_ menu will help you find more if you need it).
In a Jupyter notebook the content is divided into _cells_, in our case we are using two kind of cells:
* Markdown cells, such as the ones into these very words are written.
* Code cells, which are running code. In these notebooks the chosen kernel is C++17, so the code is C++17 which is interpreted by cling.
There are two modes:
* Edit mode, in which you might change the content of a cell. In this mode the left part of the cell is in green.
* Command mode, in which you might take actions such as changing the type of a cell, create or delete a new one, etc...
To enter in edit mode, simply type on 'Enter'.
To enter in command mode, type 'Esc'.
To execute a cell, type 'Shift + Enter'. For a markdown cell it will edit nicely the content by interpreting the markdown, and for a code cell it will run the code.
In command mode, several handy shortcuts are there; I would recommend especially:
* `a` (add a cell above)
* `b` (add a cell below)
* `x` (cut a cell)
* `M` (change cell mode to Markdown)
The complete list is available in _Help_ > _Keyboard_ shortcut.
If for some reason the code in the notebook seems stuck, you might try to restart the kernel with one of the restart option in the _Kernel_ menu.
### Restarting the kernel
#### Restarting the kernel
Sometimes something that should work doesn't... In this case try restarting the kernel: it might fix your issue!
### Table of contents
#### Table of contents
The table of content for a given notebook is available as a side panel if you go to _View_ > _Table of contents_ or if you click on the third item on the leftmost panel.
%% Cell type:markdown id: tags:
## Very basic C++ syntax (in notebook and in general)
### Semicolons
In C++ most instructions end by a semicolon `;`. If you forget it, the underlying compiler doesn't understand the syntax.
%% Cell type:code id: tags:
``` C++17
``` c++
{
int foo = 5 // COMPILATION ERROR!
}
```
%% Cell type:code id: tags:
``` C++17
``` c++
{
int foo = 5; // OK
}
```
%% Cell type:markdown id: tags:
Spaces, end lines and tabulations act as word separators; utterly unreadable code as the one below is perfectly fine from the compiler standpoint:
%% Cell type:code id: tags:
``` C++17
``` c++
# include <string>
{
int number ; number = 1
; std::string name;
name=
"truc" ;
number = 2
;
}
```
%% Cell type:markdown id: tags:
### Input / output
Inputs and outputs aren't directly a part of the language itself, but are in the standard library (often abbreviated as STL for *Standard Template Library* even if some purist may yell and explain it's not 100 % the same thing...). You therefore need to __include__ a file named `iostream`; doing so will enable the use of the input / output facilities.
%% Cell type:code id: tags:
``` C++17
``` c++
{
std::cout << "Hello world!" << std::endl; // Should fail (unless you run a cell that includes iostream before)
}
```
%% Cell type:code id: tags:
``` C++17
``` c++
#include <iostream>
{
std::cout << "Hello world!" << std::endl; // Should work: std::cout and std::endl are now known.
}
```
%% Cell type:markdown id: tags:
- `std::cout` is the symbol to designate the standard output (i.e. your screen...)
- `std::endl` is the symbol to clean-up the stream and go to next line.
The operator `<<` is used to indicate what you direct toward the stream; here `std::cout << "Hello world!"` tells to redirect the string toward the standard output.
We will see that a bit more in detail in [a later chapter](./1-ProceduralProgramming/6-Streams.ipynb), but printing something is really helpful early on hence this brief introduction here.
%% Cell type:markdown id: tags:
### Comments
There are two ways to comment code in C++:
- `//` which comments all that is after this symbol on the same line.
- `/*` ... `*/` which comments everything between the symbols.
%% Cell type:code id: tags:
``` C++17
``` c++
{
int i = 0; // Everything after // is commented until the end of the line
/*
commented...
also commented...
*/
int j = 5; // no longer commented
/*
// This type of comment might be used inside the other style
*/
}
```
%% Cell type:markdown id: tags:
[© Copyright](COPYRIGHT.md)
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment