Matreshka's User's Guide
Installation
Linux and other POSIX environment
To install Matreshka unpack its source code archive and run
make make install
Automatic configuration utility will be build and run to configure Matreshka to meet your machine and operating system.
Windows 64bit
On Windows system you need make
, install
and a few other commands.
The easiest way to get them is to install
Make and
CoreUtils
packages from GnuWin32 port.
Note for Windows 10 users: Windows assumes that "install" should ask for elevated privileges and prevents it to work as expected. To workaround that issue launch the Local Security Policy editor and
- Go to Local policies ‣ Security Options
- Set User Account Control: Detect application installations and prompt for elevation to disabled
Another option to get make
and install
- use msys2, MinGW or Cygwin environment.
Install Ada compiler from GNAT Community 2018 Release. Optionally you can install ASIS (from the same release) to enable A2JS translator.
Another option is usage of msys2 compiler distribution. Installation instructions for msys2:
- Download and install msys2 as described on https://msys2.github.io/
- Install Ada compiler `pacman -S mingw-w64-gcc-ada
- Now you need to replace unworking *.dll.a with corresponding dll. Do this in msys2 console:
adalib=$(dirname `gcc -print-libgcc-file-name`)/adalib bin_dir=$(dirname `which gcc`) rm -f ${adalib}/libgna{t,rl}-*.dll.a cp ${bin_dir}/libgna{t,rl}-*.dll ${adalib}/
- To install gprbuild setup our repository with precompiled packages:
echo [ci.mingw] >> /etc/pacman.conf echo SigLevel = Optional >> /etc/pacman.conf echo Server = https://dl.bintray.com/reznikmm/msys2/ >> /etc/pacman.conf
- Install gprbuild-gpl (and asis if you like a2js):
pacman -S mingw-w64-gprbuild-gpl mingw-w64-asis
- Continue with
make && make install
Windows 32bit
You can use GNAT GPL 2017 Windows compiler. You also need make
and install
utilities, see Windows 64bit for details.
Mac OS
You may use GNAT GPL 2016 or GCC 8.1 from sf.net.
On Mac OS system you need "Command Line Tools for XCode" installed. You can install this from Xcode menu > Preferences > Downloads or, alternatively, there are stand-alone installation packages for it.
Advanced installation
Sometimes, it is needed to have more control over configuration and build of Matreshka. One example is use Matreshka on Windows, where detection of non-standard libraries is problematic. Another example is binary packages supporters.
So, build of Matreshka consists from several steps:
- build of configuration utility;
- execution of configuration utility;
- build of package;
- installation of package.
Build of configuration utility
Configuration utility can be build by using
make config
Execution of configuration utility
Execution of configuration utility in its simplest form looks like:
./configure
This is exactly what default make target do, so there is no reasons to use it.
Configuration utility allows to specify several additional parameters all of them are reported by
./configure --help
Below is small example of manual execution of configuration utility to install Matreshka in specified directory and to lookup SQLite's libraries in the specified directory on Windows:
configure.exe --prefix=C:\Matreshka --with-sqlite3-libdir=C:\Matreshka\lib
It is possible to disable build of some Matreshka's modules. For example, to disable AMF module run configuration utility with --disable-amf switch:
./configure --disable-amf
Build of Matreshka
To build Matreshka after manual configuration it is sufficient to run
make
Several make's variables can be used to adjust build process:
- SMP_MFLAGS can be used to utilize several CPUs to compile Matreshka;
- GNAT_OPTFLAGS can be used to pass additional user defined switches for compiler.
Installation of Matreshka
And to install Matreshka:
make install
Install target is used DESTDIR environment variable to adjust root directory, it is very useful for binary packages supporters.
Run test suite
To run test suite execute
make check
This will start tests corresponding to configured settings.
Configuration to run Oracle tests
To start SQL Oracle driver tests you need an account on Oracle database server. Configure SQL*Net name TEST to point to database and set environment variables ORACLE_TEST_USER, ORACLE_TEST_PASSWORD with user's login and password. Here is example:
$ export ORACLE_TEST_USER=TEST29 $ export ORACLE_TEST_PASSWORD=test_pwd $ export TNS_ADMIN=/home/farm/tns_admin $ $ cat /home/farm/tns_admin/tnsnames.ora TEST = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521)) (CONNECT_DATA = (SERVICE_NAME = DB)) )
Configuration to run MySQL tests
Tests of MySQL driver needs to establish connection to MySQL server. 'test' database must be created and accessible to read/write by current user before run of Matreshka configuration utility. Configuration utility do some checks using mysql command line client to detect whether MySQL server is accessible. Note, MySQL tests are disabled when these checks fail.
Debugging of appications
Matreshka provides GDB plugin to pretty printing of provided data types: you will see textual representation of actual data instead of content of internal data structures.
Setup of plugin for GDB
You need to copy gdb/python/matreshka.py file to somewhere in you file tree and add line to load this file into .gdbinit file:
source <path>/matreshka.py
Next time you run GDB it will load plugin to pretty print Matreshka's data types. Note, due to GDB architecture this works only on objects of Matreshka's datatypes, not on user defined record or array types. Thus, if you debugging following code:
type Person is record Name : League.Strings.Universal_String; end record; Obj : Person;
the only way to print value of Obj.Name is to use
print Obj.Name