@c -*- texinfo -*-

@c Copyright (C) 2008, 2009, 2010, 2011, 2012 Moreno Marzolla
@c
@c This file is part of the queueing toolbox, a Queueing Networks
@c analysis package for GNU Octave.
@c
@c The queueing toolbox is free software; you can redistribute it
@c and/or modify it under the terms of the GNU General Public License
@c as published by the Free Software Foundation; either version 3 of
@c the License, or (at your option) any later version.
@c
@c The queueing toolbox is distributed in the hope that it will be
@c useful, but WITHOUT ANY WARRANTY; without even the implied warranty
@c of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with the queueing toolbox; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@ifset INSTALLONLY
@include conf.texi

This file documents the installation procedure of the Octave
@code{queueing} toolbox.

@code{queueing} is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License, version 3
or later, as published by the Free Software Foundation.

@quotation Note
This file (@file{INSTALL}) is automatically generated from
@file{doc/installation.txi} in the @code{queueing} subversion sources.
Do not modify this document directly, as changes will be lost. Modify
the source @file{doc/installation.txi} instead.
@end quotation

@end ifset

@node Installation
@chapter Installing the queueing toolbox

@menu
* Installation through Octave package management system::
* Manual installation::
* Development sources::
* Using the queueing toolbox::
@end menu

@c
@c
@c

@node Installation through Octave package management system
@section Installation through Octave package management system

The most recent version of @code{queueing} is @value{VERSION} and can
be downloaded from Octave-Forge

@url{http://octave.sourceforge.net/queueing/}

Additional information can be found at

@url{http://www.moreno.marzolla.name/software/queueing/}

If you have a recent version of GNU Octave and a network connection,
you can install @code{queueing} directly from Octave command prompt
using this command:

@example
octave:1> @kbd{pkg install -forge queueing}
@end example

The command above will automaticall download and install the latest
version of the queueing toolbox from Octave Forge, and install it on
your machine. You can verify that the package is indeed installed:

@example
octave:1>@kbd{pkg list queueing}
Package Name  | Version | Installation directory
--------------+---------+-----------------------
    queueing *|   @value{VERSION} | /home/moreno/octave/queueing-@value{VERSION}
@end example

Alternatively, you can first download @code{queueing} from
Octave-Forge; then, to install the package in the system-wide
location issue this command at the Octave prompt:

@example
octave:1> @kbd{pkg install @emph{queueing-@value{VERSION}.tar.gz}}
@end example

@noindent (you may need to start Octave as root in order to allow the
installation to copy the files to the target locations). After this,
all functions will be readily available each time Octave starts,
without the need to tweak the search path.

If you do not have root access, you can do a local install using:

@example
octave:1> @kbd{pkg install -local queueing-@value{VERSION}.tar.gz}
@end example

This will install @code{queueing} within your home directory, and the
package will be available to your user only. 

@quotation Note 
Octave version 3.2.3 as shipped with Ubuntu 10.04 seems to ignore
@code{-local} and always tries to install the package on the system
directory.
@end quotation

To remove @code{queueing} simply use

@example
octave:1> @kbd{pkg uninstall queueing}
@end example

@c
@c
@c

@node Manual installation
@section Manual installation

If you want to manually install @code{queueing} in a custom location,
you can download the tarball and unpack it somewhere:

@example
@kbd{tar xvfz queueing-@value{VERSION}.tar.gz}
@kbd{cd queueing-@value{VERSION}/queueing/}
@end example

Copy all @code{.m} files from the @file{inst/} directory to some
target location. Then, start Octave with the @option{-p} option to add
the target location to the search path, so that Octave will find all
@code{queueing} functions automatically:

@example
@kbd{octave -p @emph{/path/to/queueing}}
@end example

For example, if all @code{queueing} m-files are in
@file{/usr/local/queueing}, you can start Octave as follows:

@example
@kbd{octave -p @emph{/usr/local/queueing}}
@end example

If you want, you can add the following line to @file{~/.octaverc}:

@example
@kbd{addpath("@emph{/path/to/queueing}");}
@end example

@noindent so that the path @file{/usr/local/queueing} is automatically
added to the search path each time Octave is started, and you no
longer need to specify the @option{-p} option on the command line.

@c
@c
@c

@ifclear INSTALLONLY

@node Development sources
@section Development sources

The source code of the @code{queueing} package can be found in the
Subversion repository at the URL:

@url{http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/}

The source distribution contains additional development files which
are not present in the installation tarball. This section briefly
describes the content of the source tree. This is only relevant for
developers who want to modify the code or documentation; normal users
of the @code{queueing} package don't need

The source distribution contains the following directories:

@table @file
@item doc/
Documentation source. Most of the documentation is extracted from the
comment blocks of individual function files from the @file{inst/}
directory.

@item inst/
This directory contains the @verb{|m|}-files which implement the
various Queueing Network algorithms provided by @code{queueing}. As a
notational convention, the names of source files containing functions
for Queueing Networks start with the @samp{qn} prefix; the name of
source files containing functions for Continuous-Time Markov Chains
(CTMSs) start with the @samp{ctmc} prefix, and the names of files
containing functions for Discrete-Time Markov Chains (DTMCs) start
with the @samp{dtmc} prefix.

@item test/
This directory contains the test functions used to invoke all tests on
all function files.

@item scripts/
This directory contains some utility scripts mostly from GNU Octave,
which extract the documentation from the specially-formatted comments
in the @verb{|m|}-files.

@item examples/
This directory contains examples which are automatically extracted
from the @samp{demo} blocks of the function files.

@item devel/
This directory contains function files which are either not working
properly, or need additional testing before they are moved to the
@file{inst/} directory.

@end table

The @code{queueing} package ships with a Makefile which can be used
to produce the documentation (in PDF and HTML format), and
automatically execute all function tests. Specifically, the following
targets are defined:

@table @code
@item all
Running @samp{make} (or @samp{make all}) on the top-level directory
builds the programs used to extract the documentation from the
comments embedded in the @verb{|m|}-files, and then produce the
documentation in PDF and HTML format (@file{doc/queueing.pdf} and
@file{doc/queueing.html}, respectively).

@item check
Running @samp{make check} will execute all tests contained in the
@verb{|m|}-files. If you modify the code of any function in the
@file{inst/} directory, you should run the tests to ensure that no
errors have been introduced. You are also encouraged to contribute new
tests, especially for functions which are not adequately validated.

@item clean
@itemx distclean
@itemx dist
The @samp{make clean}, @samp{make distclean} and @samp{make dist}
commands are used to clean up the source directory and prepare the
distribution archive in compressed tar format.

@end table

@end ifclear

@c
@c
@c

@node Using the queueing toolbox
@section Using the queueing toolbox

You can use all functions by simply invoking their name with the
appropriate parameters; the @code{queueing} package should display an
error message in case of missing/wrong parameters. You can display the
help text for any function using the @command{help} command. For
example:

@example
octave:2> @kbd{help qnmvablo}
@end example

prints the documentation for the @command{qnmvablo} function.
Additional information can be found in the @code{queueing} manual,
which is available in PDF format in @file{doc/queueing.pdf} and in
HTML format in @file{doc/queueing.html}.

Within GNU Octave, you can also run the test and demo blocks
associated to the functions, using the @command{test} and
@command{demo} commands respectively. To run all the tests of, say,
the @command{qnmvablo} function:

@example
octave:3> @kbd{test qnmvablo}
@print{} PASSES 4 out of 4 tests
@end example

To execute the demos of the @command{qnclosed} function, use the
following:

@example
octave:4> @kbd{demo qnclosed}
@end example