Skip to content

various cleanup of README #860

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TallTed wants to merge 2 commits into
base: develop/7
Choose a base branch
from
+147 −119
Open

various cleanup of README #860

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6526c40
various README cleanup
TallTed Jul 23, 2019
a46222c
Merge branch 'develop/7' into fix/TallTed-20190723-README-cleanup
TallTed Dec 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 147 additions & 119 deletions README
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,8 @@ Introduction
This document explains steps to take after obtaining a Virtuoso source
snapshot or git clone.

These sections explain how to compile, test and install and what
components are produced by the make process and how one can interact
with them.
These sections explain how to compile, test, and install; what components
are produced by the make process; and how one can interact with them.


Package Dependencies
Expand All @@ -66,18 +65,18 @@ To generate the configure script and all other build files necessary,
please make sure the following packages and recommended versions are
installed on your system.

| Package | Minimum | Upto | From |
| --------- | ------- | ------ | ------------------------------------- |
| autoconf | 2.57 | 2.69 | http://www.gnu.org/software/autoconf/ |
| automake | 1.9 | 1.16.1 | http://www.gnu.org/software/automake/ |
| libtool | 1.5 | 2.4.6 | http://www.gnu.org/software/libtool/ |
| flex | 2.5.33 | 2.6.4 | http://flex.sourceforge.net/ |
| bison | 2.3 | 3.5.1 | http://www.gnu.org/software/bison/ |
| gperf | 3.0.1 | 3.1 | http://www.gnu.org/software/gperf/ |
| gawk | 3.1.1 | 5.0.1 | http://www.gnu.org/software/gawk/ |
| m4 | 1.4.1 | 1.4.18 | http://www.gnu.org/software/m4/ |
| make | 3.79.1 | 4.2.1 | http://www.gnu.org/software/make/ |
| OpenSSL | 0.9.8e | 1.1.1 | http://www.openssl.org/ |
| Package | Minimum | Maximum | From |
| --------- | ------- | ------- | ------------------------------------- |
| autoconf | 2.57 | 2.69 | http://www.gnu.org/software/autoconf/ |
| automake | 1.9 | 1.16.1 | http://www.gnu.org/software/automake/ |
| libtool | 1.5 | 2.4.6 | http://www.gnu.org/software/libtool/ |
| flex | 2.5.33 | 2.6.4 | http://flex.sourceforge.net/ |
| bison | 2.3 | 3.5.1 | http://www.gnu.org/software/bison/ |
| gperf | 3.0.1 | 3.1 | http://www.gnu.org/software/gperf/ |
| gawk | 3.1.1 | 5.0.1 | http://www.gnu.org/software/gawk/ |
| m4 | 1.4.1 | 1.4.18 | http://www.gnu.org/software/m4/ |
| make | 3.79.1 | 4.2.1 | http://www.gnu.org/software/make/ |
| OpenSSL | 0.9.8e | 1.1.1 | http://www.openssl.org/ |

and any GNU packages required by these. The autogen.sh and configure
scripts check for the presence and right version of some of the required
Expand All @@ -87,8 +86,8 @@ The `Minimum` column contains the oldest known versions of these
packages capable of building Virtuoso. Older versions of these
packages can sometimes be used, but could cause build problems.

The `Upto` column contains the most recently tested version of these
packages.
The `Maximum` column contains the most recently tested version of
these packages.

To check the version number of the tools installed on your system,
use one of the following commands:
Expand All @@ -104,73 +103,99 @@ use one of the following commands:
* make --version
* openssl version

If you have an older version than automake version 1.9 you can edit
the configure.ac script around line 47 using the examples provided for
If you have an `automake` version older than 1.9, you can edit the
`configure.ac` script around line 47 using the examples provided for
each version.

Note that many operating systems (particularly all Linux distibutions)
split some of these packages into runtime and development packages,
so users of these platforms may need to run e.g.:
Note that current operating systems (particularly all Linux distibutions)
split some of these packages into runtime and development packages, so,
users of these platforms may need to run one of the following commands
to get development headers & libraries for, for instance, OpenSSL,
even if OpenSSL runtime components are already present:

apt-get install libssl-dev

or
-- or --

yum install openssl-devel
yum install openssl-devel

to get development headers & libraries for OpenSSL.
**NOTE** OpenSSL 1.1 cannot currently be used to build Virtuoso, due to
significant changes relative to prior versions. The necessary commands
to get the OpenSSL 1.0 development tools vary with the specific Linux
distribution and package manager. For instance --

* apt (common on Debian) --

sudo apt install libssl1.0-dev

-- or --

sudo apt-get install libssl1.0-dev

* yum (common on older versions of Fedora)

yum install openssl-devel

* dnf (common on recent versions of Fedora) --

- before building Virtuoso --

sudo dnf install compat-openssl10-devel --allowerasing

- after building Virtuoso, before building anything else that
requires OpenSSL 1.1 --

sudo dnf install openssl-devel --allowerasing


Diskspace Requirements
======================

The build produces a demo database and Virtuoso application packages
that are quite large. At least 800 MB of free space should be available
in the build file system.
The complete build produces a demo database and Virtuoso application
packages that are quite large. At least 800 MB of free space should be
available in the build file system.

When running `make install', the target file system should have about 460
MB free. By default, the install target directories are under /usr/local/,
but you can specify
When running `make install`, the target file system should have about
460 MB free. By default, the install target directories are under
`/usr/local/`, but you can specify something different with --

./configure --prefix=/path/to/dir

instead.

The minimum working configuration consists of the server executable
and config files plus database, no more than a few MB for the server
executable, depending on platform and options.
(generally only a few MB, depending on platform and options) and
config files plus database.


Make FAQ
========

In the root directory of the checkout perform the following commands:
In the root directory of the checkout, perform the following commands
to produce the default binaries, VAD packages, and demo database:

./autogen.sh # should only be needed in git clone
./configure
make

to produce the default binaries, VAD packages and demo database. This
takes some time, principally due to building and filling the demo
database, rendering the XML documentation into several target formats
and composing various Virtuoso application packages. It takes about 30
minutes on a 2GHz machine.
This will take some time, principally due to building and filling the
demo database, rendering the XML documentation into several target
formats, and composing various Virtuoso application packages. It takes
about 30 minutes on a 2GHz machine.

The default configure does not enable most of the runtime-hosting and
extension features. See the links on the building page for instructions
on how to enable these and what additional software is required.
The default `configure` does not enable most of the runtime-hosting and
extension features. See the building page for instructions on how to
enable these and for notes about what additional software is required.

Some builds require additional C compiler and other environment flags to
be set before running the configure command, especially when building
64-bit versions of the server. If your system is not in this list,
please try to run the configure command without any environment settings.
Some builds require additional `C` compiler and other environment flags
to be set before running the configure command, especially when building
64-bit versions of the server. If your system is not in the list below,
try running the `configure` command without any environment settings.

Warning: if VAD or other packages fail to be built, especially on
64-bit Linux platforms, ensure you're not using excessive optimization.
CFLAGS="-O2" is known to work but there are reports of -O3 failing.
Warning: Some packages may fail to build, especially on 64-bit Linux
platforms, when using excessive optimization. `CFLAGS="-O2"` is known
to work, but there are reports of `CFLAGS="-O3"` failing.

If your system requires additional flags not listed below, please contact
us at <vos.admin@openlinksw.com>.
If your system requires additional flags not listed below, please
contact us at <vos.admin@openlinksw.com>.

Generic build environment
-------------------------
Expand Down Expand Up @@ -339,9 +364,8 @@ Mac OS X 10.7 Universal

Solaris 2.x i386 32-bit
-----------------------
Note: on Solaris or Open Solaris we recommend you use gmake either from
/usr/ sfw/bin/ or install it from sunfreeware, as long as it's version
3.80 or better.
Note: on Solaris or Open Solaris we recommend you use gmake version
3.80 or better, from /usr/sfw/bin/ or installed from sunfreeware.

CC=cc
CFLAGS="-O"
Expand Down Expand Up @@ -384,121 +408,125 @@ Solaris 2.8 and above SPARC 32-bit
Installation
============

After running configure && make,
After running `configure` and `make`, running the following command at
the root of the build tree copies the files to the location specified by
the `--prefix` option to `configure`:

make install

at the root of the build tree copies the files to the locations
specified by the --prefix option to configure. The default of --prefix
is /usr/local/. You can override this by specifying `make install
prefix=/home/virtuoso' instead, for example.
You can override the `--prefix` set with `configure` (including the
default, `/usr/local/`) for the `make install` with a command like --

These subdirectories are all appended to the specified prefix,
i.e. /usr/local/ by default:
make install prefix=/home/virtuoso

Several subdirectories are created and/or populated below the specified
prefix (whether `/usr/local/`, `/home/virtuoso/`, or otherwise), with
contents as noted:

* share/virtuoso/doc/html
* share/virtuoso/doc/pdf
* share/virtuoso/vad - VAD packages BPEL, Conductor, tutorials, documentation
* share/virtuoso/vad - VAD packages including BPEL, Conductor, tutorials,
and documentation
* var/lib/virtuoso/db - Empty database
* var/lib/virtuoso/demo - Demo database - obsolete as of version 5.0.3
* bin/ - The virtuoso-t, isql, isqlw, virt_mail, virtuoso-sample-t, inifile
executables
* lib/ - libvirtuoso-t.a libvirtuoso-t.la virtodbc32.a virtodbc32.la
virtodbc32 r.a virtodbc32_r.la virtodbc_r.so wikiv.so, plus any plugins
that may be enabled.
* lib/virtuoso - hosting sample.a hosting_sample.la hosting_sample.so
plugin_sample.a plugin_sample.so
* var/lib/virtuoso/demo - Demo database; obsolete as of version 5.0.3
* bin/ - Primarily executables such as virtuoso-t, isql, isqlw, virt_mail,
virtuoso-sample-t, and inifile
* lib/ - libvirtuoso-t.a, libvirtuoso-t.la, virtodbc32.a, virtodbc32.la,
virtodbc32_r.a, virtodbc32_r.la, virtodbc_r.so, and wikiv.so, plus any
plugins that may be enabled.
* lib/virtuoso - hosting_sample.a, hosting_sample.la, hosting_sample.so,
plugin_sample.a, plugin_sample.so

Note: as of version 5.0.2, the ./configure script supports different
subdirectory structures with the --with-layout= parameter. If you've
specified something other than the default, the above may differ
accordingly.
Note: As of version 5.0.2, the `./configure` script supports different
subdirectory structures which may be specified with the `--with-layout=`
parameter. If you've specified a layout other than the default, the above
will differ accordingly.

As of version 5.0.3, the demo is a VAD package, not a separate directory.
Note: As of version 5.0.3, the demo database is delivered as a VAD package,
not a separate directory.


Test Suite
==========

Optionally, you can run
Optionally, you can run the following at the root of the build tree to
start the automated test suite:

make check

at the root of the build tree to start the automated test suite. This
takes about an hour on a 2GHz machine and requires approximately 1 GB
of free disk space.
This requires approximately 1 GB of free disk space and takes about an
hour on a 2GHz machine.


Getting Started
===============

Run
Run the following to start the server in the background (albeit in
foreground mode):

cd var/lib/virtuoso/db
virtuoso-t -f &

to start the server in the background. It will not detach from the shell,
so you see the startup messages.
It will not detach from the shell, so you will see the startup messages.

By default, when no -c parameter is specified, virtuoso will use the
virtuoso.ini file in this directory, which is generated as part of
`make install'.
By default (i.e., when no `-c` parameter is specified), Virtuoso will use
the `virtuoso.ini` config file in the present working directory. A default
config file is generated in the `{prefix}/var/lib/virtuoso/db` directory as
part of `make install`.

The first time it's run, it will create the empty database (no special
commands required) and install the Conductor VAD package. From here, you
can access http://localhost:8890/ and http://localhost:8890/conductor/ and
use the System Administration / Packages page to install other packages
such as Demo and the ODS suite (addressbook, weblog, feeds manager and
other applications) etc.
The first time Virtuoso is run (no special commands are required), it will
create an empty database and install the Conductor VAD package. You can then
access <http://localhost:8890/> and/or <http://localhost:8890/conductor/>
and use the `System Administration` -> `Packages` page to install more VAD
packages such as the Demo catalog/database, or the ODS application suite
(addressbook, weblog, feeds manager, etc.).

The default login is `dba' with a password of `dba' for the Conductor and
isql (for DAV functions, the default login is `dav' with a password of
`dav').
The default username is `dba` with a password of `dba` for the Conductor
and iSQL. For DAV functions, the default username is `dav` with a password
of `dav`.

You will see a checkpoint in the terminal for each package selected:
You will see a `checkpoint` in the terminal for each package you install:

15:33:54 INFO: Checkpoint made, log reused

To connect with the command line SQL tool,

isql 1112 dba dba
To connect with the command line iSQL tool (i.e., to get a `SQL>` prompt),
run --

gives a SQL> prompt.
isql 1111 dba dba

If you've installed the demo VAD above, type
SQL> use Demo;
If you've installed the `demo` VAD containing the Microsoft Northwind
sample tables, you can type the following at the `SQL>` prompt to switch
to the demo database:

to switch to the demo database, containing the Microsoft Northwind sample
tables. The `help' command in isql gives further instructions.
use Demo;

The simple `help` command in iSQL will get further instructions.

To use the web admin interface, point the browser to:
To use the HTTP browser-based admin interface, point your browser to --

http://localhost:8890/conductor

To read the documents online:
To read the local documentation, visit --

http://localhost:8890/doc/html

To experiment with online tutorials you can use the conductor to install
the Tutorial vad package into your database, then point the browser to:
To experiment with online tutorials, you can use the Conductor to install
the Tutorial VAD package, then point your browser to --

http://localhost:8890/tutorial


VAD Packages
============

The different VAD packages can be installed via ISQL using the following
command (if the installation packages reside in the filesystem):

SQL> vad_install ('file/system/path/package-name.vad', 0);
Any VAD package accessible in the filesystem (and contained within the
list of `DirsAllowed` specified in the `[Parameters]` section of the
config file) can be installed via iSQL using the following command form
at the `SQL>` prompt:

Alternatively, you can copy VAD packages to Virtuoso's DAV repository
and then execute the following command (also from ISQL):
vad_install ('file/system/path/package-name.vad', 0);

SQL> vad_install ('webdav/path>/package-name.vad', 1);
Alternatively, you can copy VAD packages into Virtuoso's DAV repository,
and then execute the following command (also at the `SQL>` prompt):

at the isql command line. Note that the DirsAllowed parameter of the
Parameters section of the ini-file must allow access to the directory
where the package file is located.
vad_install ('DAV/webdav/path/package-name.vad', 1);