add README

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:
+
+```
+<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
+
+# 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.

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