Bogue tutorials — General instructions

Welcome to the Bogue tutorials!

These tutorials can be simply read online, but of course it's better (and more fun!) to execute the various code chunks by yourself. In fact, all tutorials have been designed so that they can be entirely compiled and executed. Hence, it's a good idea to install the bogue-tutorials package on your machine:

opam install bogue-tutorials

This will not only download the tutorials (you can then view them locally with firefox $(opam var bogue-tutorials:doc)/index.html), but also ensure that the whole code is compatible with your Bogue install. In fact, if you didn't install Bogue beforehand, this will automatically install a compatible version. You can also download the source and opam install .; in both cases you may append the option --deps-only if you don't want to install anything.

How to execute these tutorials

Option 1: Interactive OCaml session

You may simply open an OCaml toplevel (for instance utop), and load Bogue:

#thread;;
#require "bogue";;

Of course we assume that you have a working OCaml environment and installed the Bogue library.

Then, you can simply follow the chosen tutorial by pasting the code chunks into the toplevel.

Another option is to execute the whole tutorial at once. For this you have two choices:

Option 2: Download the source

First, you need to download the complete repository:

git clone https://github.com/sanette/bogue-tutorials.git
cd bogue-tutorials

Then, you can execute any tutorial with the command: make exe from within the tutorial directory. For instance, running the "Hello world" tutorial goes as follows:

cd hello
make exe

A benefit for having downloaded the repo: you may access all tutorials locally, by opening the file docs/bogue-tutorials/index.html in a browser.

Option 3: Install the package

opam install bogue-tutorials

Then the executables bogue-tutorials.xxx will be automatically installed. For instance, for running the "Hello world" tutorial, just run

bogue-tutorials.hello

Several examples in a tutorial?

No problem: if the tutorial opens several Bogue instances, just close the current Bogue window to allow the next one to open.

Ready?

Then let's start:

  1. Hello world
  2. A simple counter
  3. Self-modifying layouts
  4. More to come...

Contributing, issues, etc.

See the Github repository.

To create a new tutorial, download the repository, cd bogue-tutorials, and execute:

common/new_tuto.sh great_tutorial "My great tutorial"

where you should replace great_tutorial by the machine name of your tutorial (it has to be different from all existing subdirectories), and My great tutorial by the full title of your tutorial.

To preview your tutorial:

cd great_tutorial
make view

You may then offer a pull request!

Warning: if you include images (which is a good idea!) make sure that their names are specific enough, because eventually the images of all tutorials will be copied into the same directory.