# Theme-D-Intr User Manual

Tommi Höynälänmaa
2020-2023 Tommi Höynälänmaa

This file is part of Theme-D-Intr.

You can redistribute and/or modify this file under the terms of the GNU Free Documentation License as published by the Free Software Foundation, either version 1.3 of the License, or (at your option) any later version.

See file `doc/GFDL-1.3` in the source code package for the license.

## Introduction

Theme-D-Intr is a software library allowing the use of the introspected GObject modules in Theme-D.

## Installation

### Debian-based Systems using Guile 3.0

- Install G-Golf. See http://www.iki.fi/tohoyn/g-golf-debian/ .
- Download theme-d-intr_0.14.0-1_all.deb and theme-d-intr-dev_0.14.0-1_all.deb and install them with commands

      	    sudo dpkg -i theme-d-intr_0.14.0-1_all.deb
      	    sudo dpkg -i theme-d-intr-dev_0.14.0-1_all.deb

- Ensure that your Guile installation file `~/.guile` contains the following lines:

      	    (use-modules (oop goops))
      	    (default-duplicate-binding-handler
      	    '(merge-generics replace warn-override-core warn last))

### Debian-based Systems using Guile 2.2

- Install G-Golf. See http://www.iki.fi/tohoyn/g-golf-debian/ . You have to build the G-Golf package for Guile 2.2.
- Create a directory for the build and copy theme-d-intr-0.14.0.tar.xz and theme-d-intr_0.14.0-1.debian.tar.xz there. Change into the directory and give the following commands:

      	    tar xvf theme-d-intr-0.14.0.tar.xz
      	    ln -s theme-d-intr-0.14.0.tar.xz theme-d-intr_0.14.0.orig.tar.xz
      	    cd theme-d-intr-0.14.0
      	    tar xvf ../theme-d-intr_0.14.0-1.debian.tar.xz

  Change `GUILE_VERSION` from 3.0 to 2.2 and `GUILE_VERSION2` from 3.0.8 to 2.2.0 in `debian/rules`. Change `guile-3.0` to `guile-2.2` in `debian/control` and remove `(>= 3.0.8)`. Give commands

      	    dpkg-buildpackage --no-sign -b
      	    cd ..
      	    sudo dpkg -i theme-d-intr_0.14.0-1_all.deb
      	    sudo dpkg -i theme-d-intr-dev_0.14.0-1_all.deb

- Ensure that your Guile installation file `~/.guile` contains the following lines:

      	    (use-modules (oop goops))
      	    (default-duplicate-binding-handler
      	    '(merge-generics replace warn-override-core warn last))

### Other UNIX Systems

- Install the G-Golf library. See https://www.gnu.org/software/g-golf/install.html .

- Unpack package `theme-d-intr-0.14.0.tar.xz` into some directory.

- Change to the subdirectory `theme-d-intr-0.14.0` and give commands

      	      ./configure --with-guile=VERSION
      	      make
      	      sudo make install-complete

  where `VERSION` is the Guile version you use (either 3.0 or 2.2).
- Ensure that your Guile installation file `~/.guile` contains the following lines:

      	    (use-modules (oop goops))
      	    (default-duplicate-binding-handler
      	    '(merge-generics replace warn-override-core warn last))

## Using Theme-D-Intr without Installing

It is possible to use the software without installing it. First give the following commands in the subdirectory `theme-d-intr-0.14.0`:

    	./configure --with-guile=VERSION
    	make

where `VERSION` is the Guile version you use (either 3.0 or 2.2). Modify the file `~/.guile` as in a normal installation (see the previous section). Now you can launch the uninstalled environment by giving command

    	./uninstalled-env bash

in subdirectory `meta`. You also have to take care that the Theme-D module search path (option `-m` for the Theme-D compiler and linker) contains the directory `xxx/theme-d-intr-0.14.0/theme-d-code`. See Theme-D User Guide for a description of the module search path.

## Example Programs

The example programs `appwindow`, `hello`, `hello2`, `hello3`, `calc`, and `theme-d-intr-demo` for GTK 4 are located in directory `/usr/share/doc/theme-d-intr-gtk4-examples/intr-gtk4-examples` and in directory `examples/intr-gtk4-examples` in the source package. You can build the example programs with command `make -f user.mk` and run them with command

    	GUILE_LOAD_PATH=../..:$GUILE_LOAD_PATH run-theme-d-program <program-name>

where `<program-name>` is the name of the target `.go` file of the program (`main.go` or `run-demo.go`). For program `hello` the command is

    	GUILE_LOAD_PATH=.:$GUILE_LOAD_PATH run-theme-d-program hello.go

If you have a Debian-based Linux operating system you have to ensure that packages `gir1.2-gtk-4.0` and `gir1.2-adw-1` are installed in your system.

The example programs `hello`, `hello2`, `hello3`, `calc`, and `theme-d-intr-demo` for GTK 3 are located in directory `/usr/share/doc/theme-d-intr-gtk3-examples/intr-gtk3-examples` and in directory `examples/intr-gtk3-examples` in the source package. You can build the example programs with command `make -f user.mk` and run them with command

    	GUILE_LOAD_PATH=../..:$GUILE_LOAD_PATH run-theme-d-program <program-name>

where `<program-name>` is the name of the target `.go` file of the program (`main.go` or `run-demo.go`). For program `hello` the command is

    	GUILE_LOAD_PATH=.:$GUILE_LOAD_PATH run-theme-d-program hello.go

If you have a Debian-based Linux operating system you have to ensure that package `gir1.2-gtk-3.0` is installed in your system.

## Writing Programs using Theme-D-Intr

It is recommended you create a new directory for your program. First you have to list the G-Golf classes and functions you use in file `intr-imports.scm`. Its format is:

    	(intr-entities
    	  (version namespace ver)
    	  ...
    	  (classes
    	    (namespace class)
    	    ...)
    	  (functions
    	    (namespace function)
    	    ...)
    	  (rejected-methods
    	    name ...)
    	  (overridden-functions
    	    (name (argument-type ...) result-type attributes)
    	    ...)
    	  (strip-boolean-result
    	    name ...))

Namespace is the library where the definitions are imported, such as `Gtk`. Class names are given in format `MyClassName`. Note that the namespace is not include in the class or function name (`Widget` instead of `GtkWidget`). Methods belonging to a class are imported automatically when the class is imported and they must not be listed in the `functions` section. Rejected methods are generic function names for which we do not generate methods. There are two main reasons for rejecting a method:

- The method name overlaps a nongeneric function name, e.g. `append`.

- The methods of some name violate the covariance rule, see Theme-D Language Manual.

The purpose of `overridden-functions` is to handle functions overridden in G-Golf. The argument types, the result type and the attributes are given in Theme-D format. The `version` specifies the version used for a namespace. The version must be enclosed in double quotes. The boolean function result of a function can be stripped by listing it under `strip-boolean-result`. See G-Golf documentation for this feature. Here is an example import file:

    	(intr-entities
    	  (version Gtk "3.0")
    	  (classes
    	    (Gtk Widget)
    	    (Gtk Window)
    	    (Gtk Button))
    	  (functions
    	    (Gtk init)
    	    (Gtk main)
    	    (Gtk main_quit))
    	  (rejected-methods
    	    append map get-style activate compare copy)
    	  (overridden-functions
    	    (gtk-container-child-get-property (<gtk-container>
    	      <gtk-widget> <string>)
    	      <object> nonpure)
    	    (gtk-container-child-set-property
    	      (<gtk-container> <gtk-widget> <string> <object>)
    	      <none> nonpure)))

The following three files are generated from the definition file:

- Interface file `_intr-imports.thi`

- Body file `_intr-imports.thb`

- Target module `_intr-imports-target.scm`

The program and modules using G-Golf should import the module `_intr-imports`. In case you have a multiple part program name, such as `(myexamples myprogram)`, module `_intr-imports` has a multiple part name too, e.g. `(myexamples _intr-imports)`. File `_intr-imports-target.scm` is used by the linked program to provide access to the introspected libraries.

The following commands are used to generate Theme-D-Intr files:

- `generate-intr-interface`

- `generate-intr-body`

- `generate-intr-target-module`

If you use a multiple part program name you must give the `-m` option for these commands. The option argument is the imports module name for the first two commands, e.g. `-m "(myexamples _intr-imports)"` and the setter module name for the fourth command, e.g. `-m "(myexamples _intr-imports-target)"`.

When you link a program using Theme-D-Intr you have to give the following options to the Theme-D linker:

- `-x "(g-golf)"`

- `-x "(guile-theme-d-intr support)"`

- `-x "<target-module>"`

- `--duplicates="merge-generics replace warn-override-core warn last"`

Here `<target-module>` is the Theme-D name of the generated target module. For a program with a single part name it is `(_intr-imports-target)`. If you use the extra support module give also option `-x "(guile-theme-d-intr support2-gtk3)"` or `-x "(guile-theme-d-intr support2-gtk4)"`.

You have to ensure that you have the introspection files for the external libraries your program uses (with G-Golf) installed in your system. If your program uses GTK and you have a Debian-based Linux system this can be ensured by having package `gir1.2-gtk-3.0` (for GTK 3.0) or `gir1.2-gtk-4.0` (for GTK 4.0) in your system.

See also the `user.mk` makefiles of the example programs `hello`, `hello2`, `calc`, and `theme-d-intr-demo`. Example program `hello` has a single part program name and the other example programs a multiple part program name.

When you run programs using Theme-D-Intr the environment variable `GUILE_LOAD_PATH` has to contain the root directory of your program. If you use a single part program name this is the directory of your program.

## Distributing Programs using Theme-D-Intr

If you use a Debian-based operating system the following packages are required to run compiled (built) Theme-D programs using Theme-D-Intr:

- `theme-d-rte`
- `th-scheme-utilities`
- `libthemedsupport`
- `theme-d-intr`

If you have a non-Debian operating system see the Theme-D User Guide for the files required to distribute a compiled Theme-D program. In addition to those, you need file `support.scm` from the Theme-D-Intr source package. If you use files `support2-gtk3.scm` or `support2-gtk4.scm` you need distribute that, too. These files have to be installed in subdirectory `guile-theme-d-support` somewhere in the Guile library search path. In UNIX systems this path usually contains directory `/usr/share/guile/site/3.0/` or `/usr/share/guile/site/2.2/`.