# ;; -*- mode: org; coding: utf-8 -*-

#+TITLE: Guile-CV INSTALL

#+BEGIN_COMMENT

Copyright (C) 2016 - 2021
Free Software Foundation, Inc.

This document is part of GNU Guile-CV.

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice
and this notice are preserved.  This file is offered as-is, without any
warranty.

#+END_COMMENT

* Guile-CV

[[http://www.gnu.org/software/guile-cv/][GNU Guile-CV]]
Image Processing and analysis in Guile
a Computer Vision functional programming library

** Dependencies

Guile-CV needs the following software to run:

	Autoconf	>= 2.69
	Automake	>= 1.14
    Makeinfo	>= 6.6
	[[http://www.gnu.org/software/guile][Guile]] 		>= 2.0.14
	  [allows 2.2, 3.0 (>= 3.0.7)]
	[[http://www.nongnu.org/guile-lib/][Guile-Lib]]	>= 0.2.5
	[[http://ukoethe.github.io/vigra/][Vigra]]		>= 1.11.0

	  Note:
	  -----

	  If you manually install Vigra, make sure you pass the cmake
	  ‑DCMAKE_BUILD_TYPE=RELEASE option, which triggers absolutely
	  essential adequate runtime optimization flags.

	[[https://github.com/BSeppke/vigra_c][Vigra C]]		>= commit 0af647d08 - Oct 28, 2018

	  The local minima and maxima interfaces have been improved, and
	  now support the full set of options provided by Vigra, to our
	  request (thank you Benjamin!).  In addition there has been a
	  few bugs fixed, including one we detected while working on
	  Guile-CV local minima bindigs.

	  Vigra_c is a C wrapper [to some of] the Vigra
	  functionality. It is currently only available by cloning its
	  source code git repository: there is no release and no
	  versioning scheme either. But no big deal, its home page has
	  an ’Installation’ section which guides you step by step.

	  Notes:
	  ------

	  (i) Make sure you pass the cmake ‑DCMAKE_BUILD_TYPE=RELEASE
	  option, which triggers absolutely essential adequate runtime
	  optimization flags;

	  (ii) Vigra C says it depends on cmake >= 3.1, but this is only
	  true if you want to build its documentation, probably not the
	  case. Most distribution still have cmake 2.8, if that is your
	  case, you may safely edit /your/path/vigra_c/CMakeLists.txt
	  and downgrade this requirement to the cmake version installed
	  on your machine;

	  (iii) Make sure the directory where libvigra_c.so has been
	  installed is ’known’, either because it is defined in
	  /etc/ld.so.conf.d, or you set the environment variable
	  LD_LIBRARY_PATH, otherwise Guile won’t find it and configure
	  will report an error.

	[[http://www.latex-project.org/][LaTex]]

	  Any modern latex distribution will do, we use [[https://tug.org/texlive/][TexLive]].

	  Guile-CV will check that it can find the standalone
	  documentclass, as welll as the following packages: inputenc,
	  fontenc, lmodern, xcolor, booktabs, siunitx, iwona.

	  [[http://www.tug.dk/FontCatalogue/iwona/][Iwona]]: this is the font used to create im-histogram
	  headers, legend indices and footers. Note that it could be
	  that it is not part of your ’basic’ LaTex distro, on debian
	  for example, iwona is part of the texlive-fonts-extra package.

** Install from the tarball

Guile-CV releases are [[http://ftp.gnu.org/gnu/guile-cv/][here]].  The latest tarballs are:

		guile-cv-0.3.0.tar.gz
		guile-cv-0.3.0.tar.gz.sig

		[ GPG Key: A3057AD7
		[ gpg --keyserver keys.gnupg.net --recv-keys A3057AD7

Assuming you have satisfied the dependencies, open a terminal and
proceed with the following steps:

	cd <download-path>
	tar zxf guile-cv-0.3.0.tar.gz
	cd guile-cv-0.3.0
	./configure [--prefix=/your/prefix] [--with-guile-site=yes]
	make
	make install

	  Special note:
	  -------------

	  Before you start to use Guile-CV, make sure you read and
      implement the recommendation made in the manual, section
      /Configuring Guile for Guile-CV/.

Happy Guile-CV!

** Install from the source

Guile-CV uses Git for revision control, hosted on Savannah, you may
browse the sources repository here.

There are currently 2 [important] branches: master and devel. Guile-CV
stable branch is master, developments occur on the devel branch.

So, to grab, compile and install from the source, open a terminal and:

	git clone git://git.savannah.gnu.org/guile-cv.git
	cd guile-cv
	./autogen.sh
	./configure [--prefix=/your/prefix] [--with-guile-site=yes]
	make
	make install

	  Special note:
	  -------------

	  Before you start to use Guile-CV, make sure you read and
      implement the recommendation made in the manual, section
      /Configuring Guile for Guile-CV/.

The above steps ensure you’re using Guile-CV bleeding edge stable
version. If you wish to participate to developments, checkout the devel
branch:

	git checkout devel

Happy hacking!

** Notes

[1] The default and --prefix install locations for source modules and
    compiled files (in the absence of --with-guile-site=yes) are:

	    $(datadir)/guile-cv
	    $(libdir)/guile-cv/guile/$(GUILE_EFFECTIVE_VERSION)/site-ccache

    If you pass --with-guile-site=yes, these locations become the Guile
    global site and site-ccache directories, respectively.

    The configure step reports these locations as the content of the
    sitedir and siteccachedir variables, respectivelly the source
    modules and compiled files install locations.  After installation,
    you may consult these variables using pkg-config:

	    pkg-config guile-cv-1.0 --variable=sitedir
	    pkg-config guile-cv-1.0 --variable=siteccachedir

    You will need - unless you have used --with-guile-site=yes, or
    unless these locations are already ’known’ by Guile - to define or
    augment your GUILE_LOAD_PATH and GUILE_COMPILED_PATH environment
    variables with these locations, respectively (or %load-path and
    %load-compiled-path at run time if you prefer (See Environment
    Variables and Load Path in the Guile Reference Manual) [fn:1]

[2] Guile-CV also installs its libguile-cv.* library files, in
    $(libdir). The configure step reports its location as the content of
    the libdir variable, which depends on on the content of the prefix
    and exec_prefix variables (also reported). After nstallation, you
    may consult these variables using pkg-config:

	    pkg-config guile-cv-1.0 --variable=prefix
        pkg-config guile-cv-1.0 --variable=exec_prefix
        pkg-config guile-cv-1.0 --variable=libdir

    You will need - unless the $(libdir) location is already ’known’ by
    your system - to either define or augment your $LD_LIBRARY_PATH
    environment variable, or alter the /etc/ld.so.conf (or add a file in
    /etc/ld.so.conf.d) and run (as root) ldconfig, so that Guile-CV
    finds its libguile-cv.* library files [fn:2].

[3] To install Guile-CV, you must have write permissions to the default
    or $(prefix) directory and its subdirs, as well as to both Guile’s
    site and site-ccache directories if --with-guile-site=yes was
    passed.

[4] Like for any other GNU Tool Chain compatible software, you may
    install the documentation locally using make install-info, make
    install-info, make install-html and/or make install-pdf.

[5] Last but not least :), Guile-CV comes with a test-suite, which we
    recommend you to run (especially before Reporting Bugs):

		make check

Footnotes:

[fn:1] In this case, you may as well decide to either alter your
       $HOME/.guile personal file, or, if you are working in a
       multi-user environmet, you may also opt for a global
       configuration. In this case, the file must be named init.scm and
       placed it here (evaluate the following expression in a terminal):

         guile -c "(display (%global-site-dir))(newline)"

[fn:2] Contact your administrator if you opt for the second solution but
       don’t have write priviledges on your system.


* Other configure scripts options

** In a terminal

	./configure --help

** Online documentation

	https://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts
