fxsdk/README.md

156 lines
5.5 KiB
Markdown
Raw Normal View History

2019-06-29 23:24:50 +02:00
# fxSDK
2021-01-25 21:28:57 +01:00
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
2019-08-04 14:03:50 +02:00
[gint kernel](/Lephenixnoir/gint).
2019-06-29 23:24:50 +02:00
2021-01-25 21:28:57 +01:00
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!
2019-06-29 23:24:50 +02:00
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
2021-01-25 21:28:57 +01:00
favorite operating system. Windows users have good support with WSL.
2019-06-29 23:24:50 +02:00
2021-01-25 21:28:57 +01:00
## Basic install and use
2019-06-29 23:24:50 +02:00
2021-01-25 21:28:57 +01:00
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
2021-04-27 15:42:36 +02:00
for Python, as well as libusb and optionally UDisks2 for fxlink. Use the
GiteaPC configuration `:noudisks2` to disable UDisks2-based features.
2021-01-25 21:28:57 +01:00
```bash
# On Debian, Ubuntu, WSL and the like:
2021-04-27 15:42:36 +02:00
% sudo apt install python3-pil libusb-dev # (Optionally) udisks2
2021-01-25 21:28:57 +01:00
# On Arch Linux, Manjaro and the like:
% sudo pacman -S python-pillow libusb # (Optionally) udisks2
2021-01-25 21:28:57 +01:00
```
Use the `fxsdk` command to manage projects. You can create an empty add-in
project with `fxsdk new` and a name for a new folder:
2021-01-25 21:28:57 +01:00
```bash
% fxsdk new MyAddin
2021-01-25 21:28:57 +01:00
```
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).
2021-01-25 21:28:57 +01:00
**Project management** with `fxsdk`
2019-06-29 23:24:50 +02:00
`fxsdk` lets you set up projects almost instantly with a default folder
2021-01-25 21:28:57 +01:00
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.
2019-06-29 23:24:50 +02:00
`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.
2021-01-25 21:28:57 +01:00
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/G3A file generation** with `fxgxa`
2019-06-29 23:24:50 +02:00
`fxgxa` is a versatile g1a/g3a file editor that creates, edits and dumps the
header of fx-9860G add-ins files. It is used to build g1a/g3a files out of a
binary program.
2019-06-29 23:24:50 +02:00
It supports PNG icons of any formats, checking the validity and checksums of
the header, repairing broken headers and dumping both the application data and
icons.
2019-06-29 23:24:50 +02:00
`fxgxa` is called automatically by the build system in your add-in, so you
2021-01-25 21:28:57 +01:00
don't need to worry about it, but here are the main commands:
* `fxgxa --g1a|--g3a`: Generate g1a/g3a files
* `fxgxa -e`: Edit g1a/g3a files
* `fxgxa -d`: Dump metadata, checksum, and icon
* `fxgxa -r`: Repair control bytes and checksums for broken files
* `fxgxa -x`: Extract icons into PNG files
2021-01-25 21:28:57 +01:00
`fxgxa` has an alias, `fxg1a`, for compatibility with fxSDK up to 2.7.0 for
which there was no g3a file editor in the fxSDK.
2021-01-25 21:28:57 +01:00
**Asset conversion** with `fxconv`
2019-06-29 23:24:50 +02:00
2021-01-25 21:28:57 +01:00
`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.
2019-06-29 23:24:50 +02:00
2021-01-25 21:28:57 +01:00
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.
2021-04-27 15:42:36 +02:00
**USB communication** with `fxlink`
`fxlink` is a USB communication tool that can be used to send files to
calculators as well as to communicate with gint's USB driver from an add-in.
Currently, the tool is a work-in-progress, and most of the work has been spent
in properly detecting, characterizing and filtering connected calculators.
The main backend is libusb. With libusb, `fxlink` can detect CASIO calculators
connected through USB and has a test mode used to prototype interactions with
gint.
`fxlink` also supports a UDisks2 backend for systems that have UDisks2; with
this backend, `fxlink` can detect Mass Storage calculators (essentially the
fx-CG series and the G-III series) connected through USB, mount them without
root access, and transfer some files all from the command-line.
2021-01-25 21:28:57 +01:00
## Manual build instructions
2019-06-29 23:24:50 +02:00
The fxSDK is platform-agnostic; a single install will cover any target
2019-07-03 19:49:48 +02:00
platforms. Here are the dependencies:
2019-06-29 23:24:50 +02:00
2021-04-27 15:42:36 +02:00
* CMake
2019-06-29 23:24:50 +02:00
* libpng ≥ 1.6
2019-07-03 19:49:48 +02:00
* Python ≥ 3.7 (might work in 3.6)
* The Pillow library for Python 3
2021-04-27 15:42:36 +02:00
* libusb 1.0
* The UDisks2 library, unless disabled
First configure; usual options are:
2019-06-29 23:24:50 +02:00
2021-04-27 15:42:36 +02:00
* `-DCMAKE_INSTALL_PREFIX` to change the install folder;
* `-DFXLINK_DISABLE_UDISKS2=1` to disable UDisks2 support in `fxlink`.
2019-06-29 23:24:50 +02:00
```sh
2021-04-27 15:42:36 +02:00
% cmake -B build
2019-06-29 23:24:50 +02:00
```
Then make and install as usual.
```sh
2021-04-27 15:42:36 +02:00
% make -C build
% make -C build install
2019-06-29 23:24:50 +02:00
```
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.