GiteaPC/README.md

# GiteaPC: A build/install automation tool

GiteaPC ("Git-Enabled Applications of Planète Casio") is a Python tool to automate the installation of programs and libraries from the [Planète Casio Git forge](https://git.planet-casio.com/). It basically clones, pulls and checks out repositories then runs configure/make/install in them. It is sometimes called a package manager for the fxSDK, since it is the recommended way to install the SDK and its libraries.

## Getting GiteaPC

**Mac OS note**: there are some adjustments, please look at [Choukas' guide](https://www.planet-casio.com/Fr/forums/topic16614-8-giteapc-installer-et-mettre-a-jour-automatiquement-des-projets-gitea.html#186763).

In order to use GiteaPC you will need Python, git and some common building tools. The following commands will install them with the package manager for common distributions:

```bash
# For users of Debian, Ubuntu, WSL on Microsft Windows, and other Debian-based:
% sudo apt install curl git python3 build-essential pkg-config

# For users of Arch Linux, Manjaro, and other Arch-based:
% sudo pacman -S curl git python3 gcc make pkgconf
```

You can then use the following one-liner to install GiteaPC with itself:

```bash
% curl "https://git.planet-casio.com/Lephenixnoir/GiteaPC/raw/branch/master/install.sh" -o /tmp/giteapc-install.sh && bash /tmp/giteapc-install.sh
```

Feel invited to [read the script first](https://git.planet-casio.com/Lephenixnoir/GiteaPC/src/branch/master/install.sh) or even install manually.

GiteaPC might ask you to add a folder to your PATH in these terms:

```
<giteapc> In order to use programs installed by GiteaPC, you will need to add their
<giteapc> install folder to your PATH. This can be done automatically when you log
<giteapc> in by adding the following command to your startup file:
<giteapc>
<giteapc>   export PATH="$PATH:/home/el/.local/bin"
<giteapc>
<giteapc> -> Press Enter to add this command to /home/el/.profile, or
<giteapc> -> Type another file name to add this command to, or
<giteapc> -> Type "-" to skip setting the PATH entirely.
```

If you don't know what it is then press Enter then log out of your computer and in again to update the PATH.

To check that the tool is properly installed, type `giteapc` in a terminal; you should get a help message. If you type `giteapc list` you will get a list of installed repositories, which should contain just GiteaPC itself. Since GiteaPC can update itself you only need to do this section once.

## Installing the fxSDK with GiteaPC

Once you have GiteaPC, you can install the fxSDK with it. There are some more system dependencies detailed below:

```bash
# For users of WSL on Microsoft Windows:
% sudo apt install cmake python3-pil libusb-1.0-0-dev libsdl2-dev libpng-dev libncurses-dev

# For users of Debian, Ubuntu, and other Debian-based:
% sudo apt install cmake python3-pil libusb-1.0-0-dev libsdl2-dev libudisks2-dev libglib2.0-dev libpng-dev

# For users of Arch Linux, Manjaro, and other Arch-based:
% sudo pacman -S cmake python-pillow libusb sdl2 udisks2 libpng ncurses patch
```

* CMake: This is the canonical build system for fxSDK tools and add-ins.
* PIL/Pillow: This image processing library is used for asset conversion in fxconv.
* libusb: This is used in fxlink to communicate with the calculator over USB.
* SDL2: This is used in fxlink to show real-time video captures.
* ncurses: For the TUI in `fxlink -t`.
* UDisks2: This is used in fxlink to copy files to the calculator on the command-line. (optional)
* GLib: This is needed to communicate with UDisks2 on the DBus interface. (optional)

On Linux you can skip UDisks2/GLib if it doesn't fit your system; in this case write `Lephenixnoir/fxsdk:noudisks2` instead of `Lephenixnoir/fxsdk` below.

First use GiteaPC to install to install the [command-line fxSDK tools](https://git.planet-casio.com/Lephenixnoir/fxsdk) and a cross-compiler ([binutils](https://git.planet-casio.com/Lephenixnoir/sh-elf-binutils/src/branch/dev) then [GCC](https://git.planet-casio.com/Lephenixnoir/sh-elf-gcc)). This will take quite long, usually about 30 minutes to build binutils and GCC. This is also a good time to compile [gdb](https://git.planet-casio.com/Lephenixnoir/sh-elf-gdb) for remote debugging.

```bash
% giteapc install Lephenixnoir/fxsdk Lephenixnoir/sh-elf-binutils Lephenixnoir/sh-elf-gcc Lephenixnoir/sh-elf-gdb
```

At this stage the cross-compiler will be installed, but not the C++ library, because the C library is not yet available. So we continue by installing the [math library](https://git.planet-casio.com/Lephenixnoir/OpenLibm) and the [C library](https://git.planet-casio.com/Vhex-Kernel-Core/fxlibc/), before reinstalling the GCC repo which will pick up where it left off and build the C++ standard library.

```bash
% giteapc install Lephenixnoir/OpenLibm Vhex-Kernel-Core/fxlibc
% giteapc install Lephenixnoir/sh-elf-gcc
```

Finally, we can install the gint kernel and any libraries we need such as [libprof](https://git.planet-casio.com/Lephenixnoir/libprof). Any repository with the `giteapc` tag ([list here](https://git.planet-casio.com/explore/repos?q=giteapc&topic=1) or with `giteapc list -r`) can be installed.

```bash
% giteapc install Lephenixnoir/gint Lephenixnoir/libprof
```

## Updating repositories

When there is a new version of a tool or library, you can update your install by typing `giteapc install -u`, which will pull and reinstall all repositories. Expensive repositories like binutils and gcc will *not* rebuild unless they change versions (which is rare and always announced) so updates should only take a few seconds.

## Detailed use

**List and search repositories**

Use `giteapc list -r` to list the online repos that can be installed with GiteaPC, and `giteapc list` to list all the repositories you have on your computer. If an additional argument is given, it will be used to filter by name and description. For example, `giteapc list -r gcc`.

**Install and update repositories**

Use `giteapc install` to install a repository and `giteapc install -u` to pull before installing (update).

**Install specific versions**

Repository names in install and build commands accept two suffixes: `@version` and `:config` (in that order). The first allows you to select a branch or a tag (with git checkout). The second allows you to customize the build with repository-specific configuration files.

For example, to install the development version of gint, one can write:

```bash
% giteapc install Lephenixnoir/gint@dev
```

Note that the repository will then remain on the `dev` branch until you explicitly install `Lephenixnoir/gint@master` to go back to the main branch.

As another example, [Lephenixnoir/sh-elf-gcc](/Lephenixnoir/sh-elf-gcc) provides a configuration called `:any` which skips version upgrades if the cross-compiler is already installed and you don't want to update it. To use that configuration, write:

```bash
% giteapc install Lephenixnoir/sh-elf-gcc:any
```

**Low-level commands**

* `giteapc fetch` allows you to clone or update (git fetch) a repository without touching anything.
* `giteapc build` allows to configure/build a repository without installing it or to recompile without reconfiguring.
* `giteapc show` allows you to see the available versions of a local or remote repository.

See the help (`giteapc --help`) for the details of the options.

**Uninstall a repository**

`gitapc uninstall` uninstalls a repository and removes the local clone; `giteapc uninstall -k` uninstalls the repository but keeps the local clone. Dependencies are not checked during an uninstall so keep an eye out for them.

## Support GiteaPC in your project

Any repository on this forge can be installed with GiteaPC provided it satisfies a few requirements:

* Have the "giteapc" topic on the web interface (which can be added by clicking the "Manage topics" link on the repo's page): this is how compatibility is announced.
* Provide a `giteapc.make` which contains some metadata, includes `giteapc-config.make` and provides four targets `configure`, `build`, `install` and `uninstall` (details below).
* Have `giteapc-config.make` in `.gitignore`. This file is a GiteaPC-managed symbolic link to the current configuration `giteapc-config-*.make` so we don't want it to dirty the clone.

The `giteapc.make` file should look like this:

```makefile
# giteapc: version=1
# giteapc: depends=Lephenixnoir/sh-elf-gcc

-include giteapc-config.make

configure:
    ...
build:
    ...
install:
    ...
uninstall:
    ...

.PHONY: configure build install uninstall
```

First the metadata; there are two for now: `version` (must be `1`) and `depends` (a list of repo dependencies). Then the inclusion of `giteapc-config.make` if it exists. And finally, the `configure`, `build`, `install`, and `uninstall` rules, where you can run whatever code you need.

You can provide configurations by adding `giteapc-config-*.make` files. Usually these would export a variable for the rest of the Makefile to use; see [sh-elf-gcc](/Lephenixnoir/sh-elf-gcc) for an example.

See also the [Lephenixnoir/Template-gint-library](https://git.planet-casio.com/Lephenixnoir/Template-gint-library) repository for a template of an fxSDK library, which comes with a decently-featured build system and supports GiteaPC.