From e8bbf63d95beab8fb3d7519766527bb5dc825e80 Mon Sep 17 00:00:00 2001 From: Lephenixnoir Date: Mon, 25 Jan 2021 21:28:57 +0100 Subject: [PATCH] update README --- README.md | 116 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 10faa79..6126cef 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,75 @@ # fxSDK -The fxSDK is a development kit for Casio graphing calculators of the family of -the fx-9860G and fx-CG 50. It's a set of command-line compilation and project -tools used to facilitate development with the +The fxSDK is a development kit for CASIO graphing calculators in the fx-9860G +and fx-CG 50 families. It provides command-line helper tools and build systems +for add-ins and libraries, and is commonly used to develop add-ins running the [gint kernel](/Lephenixnoir/gint). -This kit is free software; you may use it for any purpose, share it, and modify -it as long as you share your changes. No credit required, but please let me -know! +The fxSDK is free software; you may use it for any purpose, share it, modify +modify it and share your changes. No credit required, but please let me know! The fxSDK is compatible with Linux and has been successfully built on Mac OS. If there are compatibility issues, I am willing to try and port stuff to your -favorite operating system. +favorite operating system. Windows users have good support with WSL. -## Tool description +## Basic install and use -A tool called fxos used to live here and has now moved to [its own +The simplest way to install the fxSDK is to use +[GiteaPC](/Lephenixnoir/GiteaPC), an automation tool that builds and installs +repositories from Planète Casio's Gitea forge. + +```bash +% giteapc install Lephenixnoir/fxsdk +``` + +The fxSDK depends on the [`sh-elf-gcc` compiler](/Lephenixnoir/sh-elf-gcc) so +GiteaPC might build it too as a dependency. You will also need the PIL library +for Python: + +```bash +# On Debian, Ubuntu, WSL and the like: +% sudo apt install python3-pil +# On Arch Linux, Manjaro and the like: +% sudo apt install python-pillow +``` + +Use the `fxsdk` command to manage projects. You can create an empty add-in +project with `fxsdk create` and a name for a new folder: + +```bash +% fxsdk create MyAddin +``` + +From that folder, you can build the add-in with the build commands: + +```bash +# Build the add-in for fx-9860G (.g1a): +% fxsdk build-fx +# Build the add-in for fx-CG 50 (.g3a): +% fxsdk build-cg +``` + +## Tools in the fxSDK + +A tool called *fxos* used to live here and has now moved to [its own repository](/Lephenixnoir/fxos). -**Project management (_fxsdk_)** +**Project management** with `fxsdk` `fxsdk` lets you set up projects almost instantly with a default folder -structure and a working Makefile linking against gint for both fx-9860G and -fx-CG 50. You can then use it to build and transfer your add-ins to a -calculator. - -Most project parameters can be changed just by editing a text file annotated -with the role and description of each option. +structure and a build system for both fx-9860G and fx-CG 50. The default build +system is CMake since version 2.3, and a bare-bones Makefile is also supported. `fxsdk` only writes files at project creation time, so you keep control over your build system and configuration - it just helps you get started faster. -**G1A file generation (_fxg1a_)** +Summary of commands (`fxsdk --help` for details): + +* `fxsdk new`: Create a new project +* `fxsdk build/build-fx/build-cg`: Configure and compile add-ins and libraries +* `fxsdk send/send-fx/send-cg`: Install files to the calculator (WIP) + +**G1A file generation** with `fxg1a` `fxg1a` is a versatile g1a file editor that creates, edits and dumps the header of fx-9860G add-ins files. It is used to build a g1a file out of a binary @@ -40,13 +78,30 @@ program. It supports PNG icons, checking the validity and checksums of the header, repairing broken headers and dumping both the application data and icon. -**Data conversion (_fxconv_)** +`fxg1a` is called automatically by the build system in your add-in, so you +don't need to worry about it, but here are the main commands: -`fxconv` is a tool that interacts specifically with gint. It converts data -files such as images and fonts into gint-specific format and embeds the result -into object files that expose a single variable. +* `fxg1a -g`: Generate g1a files +* `fxg1a -e`: Edit g1a files +* `fxg1a -d`: Dump metadata, checksum, and icon +* `fxg1a -r`: Repair control bytes and checksums for broken files +* `fxg1a -x`: Extract icon into a PNG file -## Build instructions +**Asset conversion** with `fxconv` + +`fxconv` is a programmable asset converter that converts images, fonts and +other common asset types into data structures usable directly in add-ins. The +built-in formats include gint images and fonts, [libimg](/Lephenixnoir/libimg) +images, and binary blobs. + +Projects can extend the support to custom types for maps, dialogs, GUI +descriptions, or other application-specific assets. Extensions to `fxconv` are +implemented in Python within the project. + +`fxconv` can be used directly on the command-line but normally you specify +parameters in `fxconv-metadata.txt` and let the build system do the magic. + +## Manual build instructions The fxSDK is platform-agnostic; a single install will cover any target platforms. Here are the dependencies: @@ -56,15 +111,9 @@ platforms. Here are the dependencies: * The Pillow library for Python 3 First configure; you can specify the install folder with `--prefix`, which -defaults to your local home folder. You can also enable or disable tools. -Broadly, you will need: - -* `fxsdk` if you want to benefit from the automated project setup -* `fxg1a` if you want to compile add-ins for fx-9860G -* `fxconv` if you want to compile gint or develop add-ins with it - -Each tool can be enabled or disabled with `--enable-` and -`--disable-`. For a default build you need no arguments: +defaults to your local home folder. You can also enable or disable tools, +although normally all of them are needed for add-in development. See +`./configure --help` for details. ```sh % ./configure @@ -80,8 +129,3 @@ Then make and install as usual. If you selected an install folder for which you don't have write access (which apparently includes the default folder on Mac OS), you will need `sudo` to install. - -## Usage instructions - -Most details are covered in the help of each individual tool, which you can get -with `-h`, `--help` or by invoking each tool without arguments.