This page explains the process to setup Alice environment and run some examples, as well as the main concepts behind the model used to share contents.

You have two options:

1. Use a docker container to quickly test what's inside Alice, or
2. Follow the detailed steps in the Tutorial below.

Using docker lets you quickly reproduce all the steps shown in the tutorial inside a docker container. Later on, if you want to participate in Alice, you can continue using the docker or, if using Linux, remove the docker container and image and install Alice in your system.

First thing you need is a docker image, named alice-adventures with the tag alpha:

   docker build --tag alice-adventures:alpha https://raw.githubusercontent.com/alice-adventures/Alice/main/Dockerfile

This will perform all tasks in the tutorial, including compiling the examples. You can safely ignore all the warning messages you'll see.

In case you want to run some GUI examples, you need to forward network port 8080 of the docker container to your local host port 8080, or any other port not used. In the example, docker port 8080 is mapped to the local host port 8088. When you are requested to connect to port 8080 (from inside the docker) you have to point your browser to localhost:8088:

   docker run --name alice -it -p8088:8080 alice-adventures:alpha

This command runs a container named alice from the docker image you've just created and opens a bash session into it.

The build process installs and compiles a repository of examples from Project Euler. You can run problems 1 to 30 from the command line, like:

   cd ~/alice/project_euler/usr/rocher
   ./bin/c0001_multiples_of_3_or_5
   ./bin/c0020_factorial_digit_sum
   ./bin/c0030_digit_fifth_power

Also, some problems provide a GUI implementation:

   ./bin/g0014_longest_collatz_sequence

This tutorial is provided for Linux¹. The only requirement before you continue is to have git and curl installed. You need also a basic linker. In Ubuntu, installing build-essential is enough.

The steps presented here are:

1. Install Alire
2. Index setup
3. Toolchain setup
4. Alice setup
5. Project Euler setup
6. Participants setup
7. Running some examples

These steps are performed in the command line with git and alr, the Alire command (see below). It is planned to provide the alice tool that will be in charge of all these steps, resource handling and Participant management (registration, sharing ..).

First of all you must download Alire, the Ada Library Repository, from the Alire website. Install it somewhere in your PATH (we suggest using /usr/local/bin).

Alire if a powerful tool that allows you to setup your preferred toolchain (compiler and build system), download crates², add and manage dependencies to your projects and publish your crates in the index of your choice. All in one!

The very first thing you must do to start working with Alire is to setup the Community Index. It contains dozens of Ada/SPARK libraries and a number of toolchains. The community index is added with

   alr index --reset-community

You have to setup the Alice index as well, a dedicated index specifically created to hold Alice crates. The Alice index is added with

   alr index --add=git+https://github.com/alice-adventures/alice-index --name=alice

Next step is to setup yor preferred toolchain:

   alr toolchain --select

This command will offer a list of possible compilers and builders that can be downloaded from the community index. We strongly recommend using the most recent gnat_native and gprbuild tools, usually the two default options.

Now it's time to get and build Alice:

   alr get alice

This command will download Alice and all its dependencies in a directory called something like alice_<version>_<commit_id>. As this folder is your main entry point to the rabbit hole Alice, we recommend renaming it.

   mv alice_* alice

Now, you can enter and build Alice environment ..

   cd alice
   alr build --release

Great!, Now you can run ./bin/alice to see that alice is still under development and not all functionality has been implemented, yet. But at least you have an idea about how alr works.

Now is a good time to introduce the Alice' current sharing model. It is subject to change in the future, depending on the new possibilities offered by Alire.

First of all, a nice picture is always welcomed:

In the picture you can see:

• Alice Framework, or environment: this is exactly what you have in your alice directory. It must be cloned from GitHub. When compiled, it builds the the alice command which is used to manage different Problem Sources supported in Alice (and more stuff to come later).

• Alice «Problem_Source»: this is the top place where all stuff related to a particular Problem Source is hosted. It is managed by alice in a mixed combination between Alire and git: Alire is used to manage dependencies and build libraries whilst git is used to update (pull) its contents.

• User_N «Problem_Source»: This is the place where Participants implement their solutions to Problems of a specific Problem Source.

This can seem too abstract right now, so let's continue.

For Participants eager to solve problems from Project Euler, this step opens the Problem Source Project_Euler. It contains all what Participants need to implement a Problem from Project Euler in Alice:

   git clone https://github.com/alice-adventures/project_euler.git
   cd project_euler
   alr build

This is the root directory for adventures in this Project Euler. Here you can download crates or repositories from other Participants, and set your own to start implementing solutions.

Before you start working in Project Euler problems, you can download some examples shared by other Participants. There will be a formal registration and sharing process, but for now the easy way is:

   ./action/usr-setup.sh

This script clones a Participant' repository in a common place, the directory usr, and accommodates some shared resources.

But before taking a look what's inside this repository, let's build it:

    cd usr/rocher
    alr build

In the bin directory you have all the binaries generated, a set of solutions implemented for a number of problems from Project Euler.

Note that there are binaries named c00* and few ones named g00*. The formers implement a command line interface. The latter implement a graphical user interface: run them and point your browser to localhost:8080.

¹Support for other operating systems will be provided soon.

²Crate is the generic name of the software packages managed by Alire.