From b8295f8c4026b3bee1dab870ee3593ea956d4e8a Mon Sep 17 00:00:00 2001 From: Lephenixnoir Date: Sun, 21 Aug 2022 19:06:16 +0200 Subject: [PATCH] add README --- README.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++++ install.sh | 2 +- 2 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f25b6d --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# GiteaPC: A build/install automation tool + +GiteaPC ("Gitea Planète Casio") is a Python tool to automate the installation of programs and libraries from the [Planète Casio Gitea forge](https://gitea.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://gitea.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://gitea.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: + +``` + In order to use programs installed by GiteaPC, you will need to add their + install folder to your PATH. This can be done automatically when you log + in by adding the following command to your startup file: + + export PATH="$PATH:/home/el/.local/bin" + + -> Press Enter to add this command to /home/el/.profile, or + -> Type another file name to add this command to, or + -> 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 + +# 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 + +# For users of Arch Linux, Manjaro, and other Arch-based: +% sudo pacman -S cmake python-pillow libusb sdl2 udisks2 +``` + +* 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. +* 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) + +If you use WSL on Windows then USB communication is not possible so some dependencies are useless; use `Lephenixnoir/fxsdk:noudisks2` instead of `Lephenixnoir/fxsdk` below. + +Similarly, 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://gitea.planet-casio.com/Lephenixnoir/fxsdk) and a cross-compiler ([binutils](https://gitea.planet-casio.com/Lephenixnoir/sh-elf-binutils/src/branch/dev) then [GCC](https://gitea.planet-casio.com/Lephenixnoir/sh-elf-gcc)). This will take quite long, usually about 30 minutes to build binutils and GCC. + +```bash +% 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](https://gitea.planet-casio.com/Lephenixnoir/OpenLibm) and the [C library](https://gitea.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 Lephenixnoir/sh-elf-gcc +``` + +Finally, we can install the gint kernel and any libraries we need such as [libprof](https://gitea.planet-casio.com/Lephenixnoir/libprof). Any repository with the `giteapc` tag ([list here](https://gitea.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://gitea.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. diff --git a/install.sh b/install.sh index f00b6f8..2a847c2 100755 --- a/install.sh +++ b/install.sh @@ -10,7 +10,7 @@ cd "$(mktemp -d)" curl "$URL" -o giteapc-master.tar.gz tar -xzf giteapc-master.tar.gz && cd giteapc -# Bootstrap the program by installing it with iself (allowing updates) +# Bootstrap the program by installing it with itself (allowing updates) python3 giteapc.py install Lephenixnoir/GiteaPC