LELEC210X project

This repository contains every thing you (student) need for the LELEC210X project.

The current directory, which we will refer to as root, contains instructions for:

1. the Git project initialization;
2. how to install dependencies;
3. how to keep your code clean;
4. and how to build the whole project.

Note

Part 4 will only be useful once you have read and worked through all the intermediate hands-on sessions.

Subdirectories are organized as follows:

• auth/: hands-on related to the authentification part.
• common/: shared tools across different parts.
• classification/: hands-on related to the classification part.
• contrib/: contributions from students.
• leaderboard/: code to run the leaderboard web-server, useful for locally testing your setup before the contest.
• mcu/: hands-on related to the MCU part and STM32CubeIDE project for the Nucleo board.
• tex/: LaTeX projects for this course. PDFs are provided on Moodle, but you can build them from source, see tex/README.md.

1. Using Git - Mandatory

This project is fully contained within one single git repository.

For this course, we have a "no git, no help" policy. That means that, if you ever need help from a professor or a teaching assistant, you must be able to provide a git diff view of your most recent changes (see recommended git tools).

1.1 Understanding Git

For this project, you will need to know more than just the basic knowledge about Git.

You need to make sure to understand the following concepts:

• Staging and committing files;
• Pulling and pushing changes;
• Git branches;
• Clone and Fork;
• Remotes;
• Merge and rebase.

To this end, we recommend the excellent Git Tutorial from W3schools, and more specifically the following sections:

• Git Tutorial
  • Git Intro
  • Git Get Started
  • Git New Files
  • Git Staging Environment
  • Git Commit
  • Git Branch
  • Git Branch Merge
• Git and GitHub
  • GitHub Get Started
  • Pull from GitHub
  • Push to GitHub
• Git Contribute
  • GitHub Fork
  • Git Clone from GitHub

Note

The above tutorial assumes a Unix (e.g., Ubuntu / macOS) terminal, so some commands like ls may not work on Windows.

You are still encouraged to read through all the other sections!

Then, we also recommend you to read the excellent Mergin vs. rebasing (French version) guide from Atlassian. This will be important when you will need to synchronize changes from different people.

1.2 Hosting your code

As mentioned in the tutorial, you can host your Git repository on any platform you would like, as long as we can have access to it if needed.

We decided to go for GitHub, but you can also choose UCLouvain's Forge, or any other platform (each platform has its specific free features).

See the Clone or Work wiki to understand how to get create your copy of this project, while maintaining it synchronized with potential updates.

1.3 Recommended Git tools

Advanced Git users may prefer to use it via the terminal (i.e., command-line), but using a graphical interface can be way more convenient to visualize the current status of your different branches, or to resolve conflicts easily.

There exists plently of applications, but we recommend:

• GitKraken, a Git tool for basic and advanced usage, with pro-version for free for students. This is maybe the best solution for beginners (since January 2026, we no longer recommend to use GitKraken due to their free version being limited to 6 months);
• Git's Visual Studio Code extension, which offers everything you need inside the Visual Studio Code editor;
• and GitHub Desktop, a very simple but good Git application.

For the list of softwares needed for this project, see INSTALL.md.

3. Keeping your code clean

Note

Please follow the install guide first.

A good rule when programming in a team is to follow the same formatting rules.

Since it can become tedious to manually format all codes to match a given set of rules, one can use a formatter or a linter.

While a linter will only warn you about potential problems in your code, the formatter will automatically edit your code to fix those problems. Note that using a linter is still useful since the range of rules covered by linters is usually much larger than those of a formatter.

To this end, we use pre-commit. It can be used as follows:

uv run pre-commit run --all-files

Tip

After running pre-commit, you will likely see many error messages: do not run away! Most of them are just good tips to help you improving your coding practices, and fixing all of them takes quite some time!

If you want to help us improve this repository, you can do so by fixing a few error messages here and there ;-)

If you want to run pre-commit on a subset of your files, use the following:

uv run pre-commit run --files file1 file2 ...
# E.g., on all files in `tex/`
find tex/ | xargs uv run pre-commit run --files

Note

The above command will likely only work on Linux or macOS.

If you want to disallow you from pushing unformatted code, you can install a git hook. A git hook is simply an action that will run every time you try to commit and check whether you passed or not the format rules.

To this end, please run:

uv run pre-commit install

After this, you should always run:

uv pre-commit run

to format staged files, before committing them.

4. Building the whole project

See INTEGRATION.