diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 169 |
1 files changed, 169 insertions, 0 deletions
@@ -0,0 +1,169 @@ +-*- mode: org -*- +#+TITLE: spine (sisudoc) (project) README +#+DESCRIPTION: README for spine search +#+FILETAGS: :spine:build:tools: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 - 2024 Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t +#+PROPERTY: header-args :exports code +#+PROPERTY: header-args+ :noweb yes +#+PROPERTY: header-args+ :eval no +#+PROPERTY: header-args+ :results no +#+PROPERTY: header-args+ :cache no +#+PROPERTY: header-args+ :padline no + +project_name: sisudoc-spine-search + + description: [ + "documents, structuring, processing, publishing", + search, + object numbering, + cgi search form for static content generator, + sisu markup + ] + + author: + name: Ralph Amissah + email: ralph.amissah@gmail.com + + copyright: "(C) 2015 - 2024 Ralph Amissah, All Rights Reserved." + + license: "AGPL 3 or later" + + homepage: [ + "https://www.sisudoc.org", + "https://www.doc-reform.org" + ] + +** Build Configuration + +sisudoc-spine-search-cgi example form is served from a web-server that has been +configured for cgi. To get this example to work, you will need to edit the file +in ./views/configuration.txt to match the configuration of your web-server and +in particular: the the web server url; the name of the cgi script and; the name +and location of the sqlite database. The following is an example +./views/configuration.txt file. + +struct Cfg { + string http_request_type = "http"; + string http_host = "localhost"; + string www_url_doc_subroot = "/spine"; + string cgi_filename = "spine_search"; + string cgi_search_form_title = "≅ SiSU Spine search ፨"; + string db_sqlite_path = "/var/www/sqlite"; + string db_sqlite_filename = "spine.search.db"; +} +enum _cfg = Cfg(); + +* Installation, Compilation + +Development of sisudoc-spine started in 2015 on a Debian linux box. + +Development since 2020 has been on a NixOS linux box, my laptop. If you are +fortunate enough to be using the same the build instructions should be presented +on entering the sisudoc-spine directory. It should be little problem building on +other linuxes with the right dependencies. At one time, debconf-18 I was +persuaded to try meson, and for a couple of years maintained a meson build, that +dropped out of use before or on my making the switch to nixos in 2020. + +❯❯ D compiler and build manager + +SiSU spine is written in the programming language D for which there are 3 +compilers: dmd, ldc, gdc +- https://wiki.dlang.org/Compilers + +D projects tend to use dub as project manager +- https://code.dlang.org/packages/dub +- https://github.com/dlang/dub/blob/master/source/dub/commandline.d + +The default build tools used are dub with ldc2 (dub is also tested) + +** make a directory and clone the sisudoc-spine project + + mkdir ~/git.sisudoc + cd ~/git.sisudoc + + git clone git://git.sisudoc.org/software/sisudoc-spine && \ + git clone git://git.sisudoc.org/software/sisudoc-spine-search-cgi && \ + git clone git://git.sisudoc.org/markup/sisudoc-spine-samples + +such a relative directory layout will be assumed in the examples that provided + +all work in this installation of sisudoc-spine-search-cgi will take place in the +directory: sisudoc-spine-search-cgi + +** build sisudoc-spine + +NOTE all actions to build sisudoc-spine are taken within the directory +sisudoc-spine-search-cgi + +cd sisudoc-spine-search-cgi + +## directly with dub +### ldc2 + # on nix (get dependencies by setting your development environment): + nix develop ".#dsh-nixpkgs-ldc-dub" --print-build-logs -c zsh + + dub run --compiler=ldmd2 --config=ldmd2 --combined --skip-registry=all + dub --compiler=ldmd2 --config=ldmd2 + + dub run --compiler=ldc2 --config=ldc2 --combined --skip-registry=all + dub --compiler=ldc2 --config=ldc2 + +### dmd + # on nix (get dependencies by setting your development environment): + nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh + + dub run --compiler=dmd --config=dmd --combined --skip-registry=all + dub --compiler=dmd --config=dmd + +## with make + +### ldc2 + + make ldc + +### dmd + + make dmd + +## with nix on linux / nixos + +### ldc2 + + nix build ".#spine-search-nixpkgs-ldc" --print-build-logs + # or + nix build ".#spine-search-overlay-ldc" --print-build-logs + +### dmd + + nix build ".#spine-search-nixpkgs-dmd" --print-build-logs + # or + nix build ".#spine-search-overlay-dmd" --print-build-logs + +## the Meson build system was used briefly + +On recommendation at debconf-18 meson was used briefly. It has neither been +tested nor used since the move to nix. + +- https://mesonbuild.com/ + + meson + ninja -C build + meson setup --wipe build && ninja -v -C build + make meson + +dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/. + +* Commands + +For commands to populate the db to be searched by sisudoc-spine-search-cgi see +the README in sisudoc-spine and/or sisudoc-spine-samples + +However, a number of command instructions provided will not work unless the +sqlite db has been initialised and like the web content, this the sqlite databse +will not be found by sisudoc-spine-search-cgi unless it is placed where the +web-server is configured to find it. |