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

#+TITLE: Guile-CV INSTALL

#+BEGIN_COMMENT

Copyright (C) 2016 - 2018
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

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.3
	[[http://www.gnu.org/software/guile][Guile]] 		>= 2.0.13
	[[http://ukoethe.github.io/vigra/][Vigra]]		>= 1.11.0

	  Special notes:
	  --------------

	  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 a2ff675f4 April 15, 2018

		new interface vigra_nonlocalmean_c (introduced in Jan
		2018), has an argument that has been renamed;

		the vigra_medianfilter_c function (updated in Jan 2018
		as well) takes an additional 'out-of-bound strategy'
		argument.

	  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.

** Quickstart

Guile-CV releases are here:

	http://ftp.gnu.org/gnu/guile-cv/

		guile-cv-0.2.0.tar.gz
		guile-cv-0.2.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.2.0.tar.gz
	cd guile-cv-0.2.0
	./configure [--prefix=/your/prefix]
	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!

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