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. 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.

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:

# 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:

% 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 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:

# 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

• 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 and a cross-compiler (binutils then GCC). This will take quite long, usually about 30 minutes to build binutils and GCC.

% giteapc install Lephenixnoir/fxsdk Lephenixnoir/sh-elf-binutils Lephenixnoir/sh-elf-gcc

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 and the C library, before reinstalling the GCC repo which will pick up where it left off and build the C++ standard library.

% 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. Any repository with the giteapc tag (list here or with giteapc list -r) can be installed.

% 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:

% 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 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:

% 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:

# 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 for an example.

See also the Lephenixnoir/Template-gint-library repository for a template of an fxSDK library, which comes with a decently-featured build system and supports GiteaPC.