From 37a5542d42d78500a907f9a22854bb93d405819c Mon Sep 17 00:00:00 2001 From: Ali Eren Yogurtcu Date: Sat, 14 Aug 2021 21:04:27 +0300 Subject: [PATCH] BUILDING.md, CONTRIBUTING.md and INSTALL.md files are added and updated --- BUILDING.md | 31 +++++----- CONTRIBUTING.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL.md | 23 +++++++ 3 files changed, 197 insertions(+), 17 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 INSTALL.md diff --git a/BUILDING.md b/BUILDING.md index 9502a62..6882539 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,21 +1,19 @@ # Building FastFingers From Source FastFingers uses the [CMake](https://cmake.org/) and -[GNU Make](https://www.gnu.org/software/make/) build tools. -Along with these tools, some libraries needs to be installed -to build FastFingers from the source. In the section below -these dependencies are described. +[GNU Make](https://www.gnu.org/software/make/) build tools. Along with these tools, some libraries needs to be installed +to build FastFingers from the source. In the section below these dependencies are described. ## Table of contents -- [Building FastFingers From Source](#building-fastfingers-from-source) - * [Dependencies](#dependencies) - + [Install Dependencies for Ubuntu/Debian](#install-dependencies-for-ubuntu-debian) - + [Install Dependencies for Fedora/CentOS](#install-dependencies-for-fedora-centos) - + [Install Dependencies for Arch/Manjaro](#install-dependencies-for-arch-manjaro) - * [Building and Installing](#building-and-installing) - + [Configure the CMake](#configure-the-cmake) - + [Compile the source files](#compile-the-source-files) - + [Install System-wide](#install-system-wide) + +* [Dependencies](#dependencies) + + [Install Dependencies for Ubuntu/Debian](#install-dependencies-for-ubuntu-debian) + + [Install Dependencies for Fedora/CentOS](#install-dependencies-for-fedora-centos) + + [Install Dependencies for Arch/Manjaro](#install-dependencies-for-arch-manjaro) +* [Building and Installing](#building-and-installing) + + [Configure the CMake](#configure-the-cmake) + + [Compile the source files](#compile-the-source-files) + + [Install System-wide](#install-system-wide) ## Dependencies @@ -31,7 +29,6 @@ You can install the required libraries and tools from package repositories: ### Install Dependencies for Ubuntu/Debian - ```bash sudo apt-get install build-essential cmake libgtk-3-0 libgtk-3-dev ``` @@ -42,28 +39,28 @@ sudo apt-get install build-essential cmake libgtk-3-0 libgtk-3-dev sudo dnf install make gcc cmake pkg-config gtk3 gtk3-devel ``` - ### Install Dependencies for Arch/Manjaro - ```bash sudo pacman -S base-devel gtk3 cmake ``` ## Building and Installing - ### Configure the CMake + ```bash cmake -S fastfingers/src -B fastfingers/src/build -DCMAKE_BUILD_TYPE=Release ``` ### Compile the source files + ```bash cmake --build fastfingers/src/build --config Release ``` ### Install System-wide + ```bash sudo cmake --build fastfingers/src/build --target install ``` \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cdc8bfe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,160 @@ +# Contribute to FastFingers + +There are a number of ways you can help improve FastFingers. You can contribute to the project by reporting issues, +making suggestions and modifying the code. + +## Table of contents +* [Design](#design) +* [How to add new applications](#how-to-add-new-applications) + + [Creating the JSON file](#creating-the-json-file) + - [Application object:](#application-object-) + - [Shortcut category object:](#shortcut-category-object-) + - [Shortcut object:](#shortcut-object-) + - [Finalizing](#finalizing) + + [Adding the logo](#adding-the-logo) + + [Adding the logo to GResource file](#adding-the-logo-to-gresource-file) + + [Integrating your work with the project](#integrating-your-work-with-the-project) + +## Design + +FastFingers is a Linux GUI application. Main libraries and tools used in the project are GTK3, GLib, CMake and cJSON. + +The UI designs are stored under "src/ui" in the XML format, which are both human-readable and interpretable by +GtkBuilder. + +FastFingers and Cheatsheet are two different executables. FastFingers starts from main.c and the Cheatsheet app starts +with cheatsheet. + +Pages files are named "(pageName)-page", custom widget files take the widget's name. main.c, fastfingers.c and +cheatsheet.c files controls the application flow. ff-utils.c file has the utility functions that are used in the +project. + +Keyboard shortcuts are stored in the "data/applications" path. Each application has their owned JSON file with a custom +format. This format is described in the section below. + +## How to add new applications + +Application files are stored in the path "data/applications". If you want to add a new application, please read the +information below to understand the design. If you want to add a new application, you should create a .json file as +described, add its logo to "src/logo", and add that logo to +"org.ccextractor.FastFingers.gresource.xml". This progress is explained step by step below. + +### Creating the JSON file + +Each application has their owned JSON file with a custom format. The name of this json file should only include lower +case characters and shouldn't contain any whitespace. + +#### Application object: + +```json +{ + "title": "Firefox", + "category": "Utility", + "recent": [], + "group": [ + ... + ] +} +``` + +* title + * This key determines the title of the application. This is the name shown in the FastFingers for the application. +* category + * This key determines the category of the application. In the home page, the applications are grouped under the + categories, so this information is important for the harmony. +* recent + * This key is used in the application run time. It should be left blank in the source. +* group + * Shortcuts of the applications are stored under the categories, and the group key has an array value that holds + those categories. + +#### Shortcut category object: + +```json +{ + "title": "Navigation", + "shortcuts": [ + ... + ] +} +``` + +* title + * This key determines the title of the shortcut category. This title is shown in the application screen. +* shortcuts + * Shortcuts that belong to this category are stored in this array. + +#### Shortcut object: + +```json + { + "title": "Back", + "keys": [ + "Alt", + "Left" + ], + "learned": 0 +} +``` + +* title + * Title is the both identifier and descriptor of the shortcut. In practice, quiz and quiz result screens, this title + is shown. Thi title should be as short as possible. +* keys + * Keys that should be pressed is stored in this array in the same order. +* learned + * Learned key is meaningful for the program and this key should be 0 in the source files. + +#### Finalizing + +After following the steps above, you should have a JSON structure like this: + +```json +{ + "title": "Firefox", + "category": "Utility", + "recent": [], + "group": [ + { + "title": "Navigation", + "shortcuts": [ + { + "title": "Back", + "keys": [ + "Alt", + "Left" + ], + "learned": 0 + } + ] + } + ] +} +``` + +To have a greater idea about the JSON files, you can take a look at existing files +at "[data/applications](https://github.com/CCExtractor/fastfingers/tree/main/data/applications)". + +### Adding the logo + +You should add the logo of the application to the + +path "[src/logo](https://github.com/CCExtractor/fastfingers/tree/main/src/logo)". Name of the file should be in the same +format with the JSON file, it should consist of lower case characters, and it shouldn't contain whitespace.These logos +are shown in the home, application, practice and quiz screens. The files scaled automatically in the application, so +there is no size rule. + +### Adding the logo to GResource file + +Application holds the logos in its executable. To do this, you should define each logo in the GResource file +at "[src/org.ccextractor.FastFingers.gresource.xml](https://github.com/CCExtractor/fastfingers/blob/main/src/org.ccextractor.FastFingers.gresource.xml)" +. + +```xml + ... +logo/fileName.png +``` + +### Integrating your work with the project + +You can send a pull request to integrate all your work with the project. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..5c5ae96 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,23 @@ +# Building FastFingers From Source + +FastFingers release Debian, Arch and RPM packages in +every release. You can download the proper package for +your Linux system from releases and ## Install them with +package managers. + + +## Install the package for Ubuntu/Debian + +```bash +``` + +## Install the package for Fedora/CentOS + +```bash +``` + + +## Install the package for Arch/Manjaro + +```bash +``` \ No newline at end of file