From 412c3da169f901d566c5ce624ea1b333f18de317 Mon Sep 17 00:00:00 2001
From: Kubat <mael.martin31@gmail.com>
Date: Tue, 26 Jan 2021 09:26:35 +0100
Subject: [PATCH] MISC: Fix chmod on downloaded utilities and update doc

---
 CONTRIBUTING.md     | 72 +++++++++++++++++++++++++++++++++++-----
 README.md           | 80 ++++++++++++++++-----------------------------
 configure           |  6 ++--
 man/footer          |  2 ++
 man/lektor.template |  2 ++
 5 files changed, 100 insertions(+), 62 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0a126627..c3cf6084 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,13 +1,20 @@
 # Contributing to Lektor
 
-Clone the [git repository](https://git.iiens.net/martin2018/lektor). Create a
-branch from master with the `git checkout -b dev-${pseudal}` command.
+- [License](#license)
+- [Building](#buidling)
+- [Debugging lektor](#debuging)
+- [Style and code](#style-and-code)
+- [Merge request titles](#merge-request-titles)
+- [Modules](#modules)
+
+---
 
-Please, rebase regularly your branch on `master`.
+Clone the [git repository](https://git.iiens.net/martin2018/lektor). Create a
+branch from master with the `git checkout -b dev-${pseudal}` command. Please,
+rebase regularly your branch on `master`.
 
 Please, add your name in the CONTRIBUTORS file. The format is `First name
-'Pseudal' FAMILY　NAME`. The licence is a modified version of the ISC licence
-to include this file (in short, a kind of MIT licence).
+'Pseudal' FAMILY　NAME`. The use license is the very permisive ISC license.
 
 ## License
 
@@ -22,18 +29,27 @@ configuration, to use the fixed version.
 An archlinux package exists, use `makepkg -si` to build and install it. If
 there are no package for your distribution, feel free to add a way to make it.
 
-Here are some recomended invocations of the `configure` script:
+Here are some possible invocations of the `configure` script:
 
 - `../configure --prefix=$HOME/.local --with-liblektor=static --enable-debug CC=clang`
+- `../configure --prefix=$HOME/.local --enable-klkt CC=clang CXX=clang++`
 - `../configure --prefix=$HOME/.local CC=gcc`
 - `../configure --prefix=$HOME/.local --with-depends`
 
+## Debuging
+
+You will need gdb. You can launch gdb on installed programs, gut you can also
+use libtool for that.  With the `libtool-bin` package installed, you can run:
+`libtool --mode=execute gdb $BUILD_DIR/src/lektord` to launch lektord with gdb.
+
 ## Style and the code
 
 ### C code and style
 
 Prefer using `__${name}` names for static variables and functions. Prefix the
 name of the file or folder in function names, e.g. `database_` or `command_`.
+If you declare functions that really nobody should used, please prefix them
+with three underscores like `___${name}`.
 
 For formating, use the `./utils/scripts/astyle.bash` from the root of the
 project. You'll need [astyle](http://astyle.sourceforge.net/) for that. Note
@@ -42,7 +58,8 @@ that the astyle step is a part of the CI/CD.
 You are encouraged to use the `./utils/scripts/tags.bash` script to build the
 `ctags` and `cscope` database files to explore more easelly the project.
 
-The C standard used here is C11, because on debian C18 doesn't compiles.
+The C standard used here is C11, because on debian C18 doesn't compiles. The
+C++ used standard is C++17, thus C++ code is currently not tested with the CI.
 
 ### Scripts
 
@@ -50,18 +67,27 @@ Scripts goes to the [scripts](utils/scripts) folder. They must be written to be
 launched from the root of the project. Include the language used in the name of
 the script, for example:
 
-- `astyle.bash`: written in bash
+- `astyle.bash`: written in bash (bourn shell again)
+- `hashire.sh`: written in sh (bourn shell)
 - `magic.rb`: written in ruby
 
 Please, do not write scripts in too many different languages to reduce the
 number of dependencies. If you are using binaries in your scripts (like astyle
 or bc), include them in the binary dependencies in the [README](README.md)
-file.
+file. Also note that `bash` and `sh` are two different shells and things that
+work in `bash` might not work with `sh`. As `bash` usually provide `sh`, it is
+fine to use the two shells in different scripts without increasing the
+dependency number.
 
 There is a strong possibility that your script will do similar things to what a
 script already in this repo do. In that case, please work on the existing
 script and enhance it with your changes. No need to duplicate things.
 
+### Utilities
+
+You can place utilities in the [utils](utils) folder. When downloading or
+building tools not dirrectly distributed with lektor this folder will be used.
+
 ## Merge request titles
 
 Try to be as more descriptive as you can in your Merge Request title. Include
@@ -78,3 +104,31 @@ the issue number and the target OS if possible.
 When adding new fetures or solving issues / bugs, please edit the
 [CHANGELOG](CHANGELOG.md) file at the `# Next` section. This will help people
 know what has been done since the last version.
+
+## Modules
+
+Modules are a way of putting modular code in lektor. It enable the user to
+select different types of players and repositories.
+
+Modules are `.so` files (i.e. dynamic libraries) loaded by lektors using a
+function named `module_set_function` which takes a `void *` and a
+`struct lkt_option *` in argument and must return an `int` (may return an
+`uint16_t` in the future). This function must initialize correctly the module.
+The name of this function can be defined in the INI file.
+
+The functions of a modules are stored in a `register`. This register can be
+registered in the lektor's global `register` or exported inside `.so` file.
+Only one `register` can be exported by `.so` file. The macros are here to help
+you do so.
+
+Some functions are mendatory for a module:
+
+- The `new(void **)` function creates the module
+- The `free(void **)` release the module, it *can't* be used after
+- The `close(void **)` close the module, it *can* be used after
+
+All exported functions must take a `va_list`. The first argument of the `va_list`
+is a `void **`, which point to the pointer used to access the module's defined
+structure. The rest is up to you, no checks will be done. All functions must return
+an `int` in a POSIX way: `0` if everything is ok, an other value if something
+went wrong.
diff --git a/README.md b/README.md
index a1131521..6ca88e7f 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ A Karaoke player made to replace the old bash scripts on Sakura.
 - [Preparing karaokes for lektor](#preparing-a-kara-for-lektor)
 - [How to use lektor](#how-to-use-lektor)
 - [Contributing](#contributing)
+- [MPD compatibility](#mpd)
 
 ## Building the player
 
@@ -76,31 +77,45 @@ If you are developping for lektor, you will need:
 The manual way of installing and setting up lektor:
 
 ```sh
-# Setup files
+# Setup files, you can also change the default kara folder and database path in
+# the config file.
 sudo mkdir /home/kara && sudo chown USER:USER /home/kara
 
-# Install
+# Install, typical with libtool.
 mkdir build && cd build && ../configure
 make
 sudo make install
 
-# Config and run
+# Config and run.
 lektord
 ```
 
+The recommended `configure` command is the following:
+
+```sh
+../configure --prefix=$HOME/.local      \ # To not need to sudo to install
+             --with-liblektor=static    \ # One big executable
+             --enable-klkt              \ # For desktop notifications
+             CC=clang CXX=clang++         # I prefer clang over gcc
+```
+
 The sqlite database and the config file will be created automatically if
 needed, i.e. on the first run. If you are upgrading lektor, the config might
 not be correct. You can delete the config file or use the `lkt admin config` to
 generate the config file again.
 
+> **Important note**: Upgrading the config or the database scheme automatically
+is not supported yet. If you are experiencing weird things with lektord, please
+try first to delete the database and config and regenerate them. There are
+currently no way of doing a backup of playlists and stickers with lektor, this
+is WIP.
+
 If you are using special modules or are compiling lektor without static modules,
 you may set their **absolute path** inside the lektor's config file.
 
-On archlinux, you need only to install the package:
-
-```sh
-makepkg -si
-```
+On archlinux, you need only to install the package: `makepkg -si`. To generate
+AppImages, add `enable-appimage` to the `configure` line. Note that doing so
+will override any defined prefix.
 
 > **Important note**: if you are building using WSL, `lektord` will likely not
 launch, because `XDG_RUNTIME_DIR` is not defined here. This folder is
@@ -111,7 +126,8 @@ have issues with sound and videos becouse you will need to set up a X server...
 
 > Currently, supported compilers are: `icc` 19.1.2.254 and above, `gcc` 8.3.0 and
 above, `clang` 7.0.1 and above. It compiles on debian, thus it must compiles on
-your system (apport from CentOS, because I never tested on it).
+your system (apport from CentOS, because I never tested on it, and it no longer
+exists...).
 
 ## Preparing a kara for lektor
 
@@ -126,11 +142,7 @@ commands are here for that. To import the favorites and playlists from
 To run lektor, you can simply run the binary like: `./lektord`. If lektord did
 not exited normally (i.e. without the `lkt adm kill` command), the database
 will still store the fact that lektord is running. To by-pass it, you will need
-to launch lektord with the `-F` (forced) option, like:
-
-```
-lektord -F
-```
+to launch lektord with the `-F` (forced) option, like `lektord -F`.
 
 It is not recommended to launch always lektord with the `-F` option, because that
 way you could launch multiple instances of the lektod daemon, which could results
@@ -138,10 +150,7 @@ in undefined behaviours.
 
 Lektor will use specialized software (hwdec set to yes), if you have an nvidia
 card with optimus (in almose every laptop), please use `optirun` or `primusrun`:
-
-```
-optirun ./lektord
-```
+`optirun ./lektord`
 
 ### How to send commands to lektor
 
@@ -156,16 +165,13 @@ Lektor configuration is done with an INI file. Modules' configuration is also
 done by the same INI file using diferent sections. Lektor searches for the
 configuration file in that order:
 
-1. `$(pwd)/lektor.ini`
+1. `$PWD/lektor.ini`
 2. if `XDG_CONFIG_HOME` defined then `$XDG_CONFIG_HOME/lektor/lektor.ini` else
    `$HOME/.config/lektor/lektor.ini`
 3. `/opt/lektor/lektor.ini`
 4. `/usr/local/etc/lektor.ini`
 5. `/etc/lektor.ini`
 
-The first one to be found is picked up by lektor. Note that if the environment
-variable `XDG_CONFIG_HOME` is not defined, it is replaced by `HOME/.config`.
-
 To get the default config file, you can use the `lkt adm conf` command. If no
 config file is found, lektord will try to create the
 `$HOME/.config/lektor/lektor.ini` config file with the default content.
@@ -177,35 +183,7 @@ will be ignored and truncated. You may then get uncomprehensible errors.
 
 Please, refer to the [CONTRIBUTING](CONTRIBUTING.md) file.
 
-### Modules
-
-Modules are a way of putting modular code in lektor. It enable the user to
-select different types of players and repositories.
-
-Modules are `.so` files (i.e. dynamic libraries) loaded by lektors using a
-function named `module_set_function` which takes a `void *` and a
-`struct lkt_option *` in argument and must return an `int` (may return an
-`uint16_t` in the future). This function must initialize correctly the module.
-The name of this function can be defined in the INI file.
-
-The functions of a modules are stored in a `register`. This register can be
-registered in the lektor's global `register` or exported inside `.so` file.
-Only one `register` can be exported by `.so` file. The macros are here to help
-you do so.
-
-Some functions are mendatory for a module:
-
-- The `new(void **)` function creates the module
-- The `free(void **)` release the module, it *can't* be used after
-- The `close(void **)` close the module, it *can* be used after
-
-All exported functions must take a `va_list`. The first argument of the `va_list`
-is a `void **`, which point to the pointer used to access the module's defined
-structure. The rest is up to you, no checks will be done. All functions must return
-an `int` in a POSIX way: `0` if everything is ok, an other value if something
-went wrong.
-
-### MPD
+## MPD
 
 Lektor is almost MPD compatible, at least it uses the same protocol, which can
 be gotten [here](https://www.musicpd.org/doc/html/protocol.html#). The full
diff --git a/configure b/configure
index f66325bb..4cca35a3 100755
--- a/configure
+++ b/configure
@@ -17474,12 +17474,14 @@ fi
   as_fn_error $? "chmod is required for AppImage" "$LINENO" 5
 fi
 
+    # TODO: Don't download if binaries are already here
+
     # Download the AppImage creation tool, transforms the AppDir into an AppImage
     { $as_echo "$as_me:${as_lineno-$LINENO}: checking Downloading AppImage creation tool" >&5
 $as_echo_n "checking Downloading AppImage creation tool... " >&6; }
     $WGET https://github.com/probonopd/AppImageKit/releases/download/continuous/appimagetool-`arch`.AppImage \
         -O $LKT_PATH_SOURCE/utils/appimagetool.AppImage -o config.wget.log
-    $CHMOD 00700 utils/appimagetool.AppImage
+    $CHMOD 00700 $LKT_PATH_SOURCE/utils/appimagetool.AppImage
     if test $? -eq 0 ; then :
   { $as_echo "$as_me:${as_lineno-$LINENO}: result: done" >&5
 $as_echo "done" >&6; }
@@ -17494,7 +17496,7 @@ fi
     { $as_echo "$as_me:${as_lineno-$LINENO}: checking Downloading LinuxDeploy creation tool" >&5
 $as_echo_n "checking Downloading LinuxDeploy creation tool... " >&6; }
     $WGET https://martinm.iiens.net/linuxdeploy -O $LKT_PATH_SOURCE/utils/linuxdeploy-`arch`.AppImage -a config.wget.log
-    $CHMOD 00700 utils/linuxdeploy-`arch`.AppImage
+    $CHMOD 00700 $LKT_PATH_SOURCE/utils/linuxdeploy-`arch`.AppImage
     if test $? -eq 0 ; then :
   { $as_echo "$as_me:${as_lineno-$LINENO}: result: done" >&5
 $as_echo "done" >&6; }
diff --git a/man/footer b/man/footer
index 3fd0a054..36c35ff3 100644
--- a/man/footer
+++ b/man/footer
@@ -4,6 +4,8 @@
 .TP
 \fB$HOME/.config/lektor/lektor.ini\fP                   general config file for the user
 .TP
+\fB$HOME/.config/lektor/klkt.ini\fP                     Klkt config file
+.TP
 \fB/home/kara/\fP                                       default prefix for the bakabase
 .TP
 \fB/home/kara/kara.db\fP                                default sqlite3 base for the bakabase
diff --git a/man/lektor.template b/man/lektor.template
index b682cae6..60beb55e 100644
--- a/man/lektor.template
+++ b/man/lektor.template
@@ -15,6 +15,8 @@ You may be interested in other related programs like:
 \fIlektord\fP       The lektor daemon
 .TP
 \fIlkt\fP           A standard client for lektord
+.TP
+\fIklkt\fP          A simple Qt/libnotify client for desktop notifications
 .PD
 
 .SH "DESCRIPTION"
-- 
GitLab