-*- 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.