Theme-D-Intr User Manual

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.


Table of Contents

Introduction
Installation
Debian-based Systems using Guile 3.0
Debian-based Systems using Guile 2.2
Other UNIX Systems
Using Theme-D-Intr without Installing
Example Programs
Writing Programs using Theme-D-Intr
Distributing Programs using Theme-D-Intr

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

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.12.0.tar.xz and theme-d-intr_0.12.0-2.debian.tar.xz there. Change into the directory and give the following commands:
    	    tar xvf theme-d-intr-0.12.0.tar.xz
    	    ln -s theme-d-intr-0.12.0.tar.xz theme-d-intr_0.12.0.orig.tar.xz
    	    cd theme-d-intr-0.12.0
    	    tar xvf ../theme-d-intr_0.12.0-2.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.12.0-2_all.deb
    	    sudo dpkg -i theme-d-intr-dev_0.12.0-2_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.12.0.tar.xz into some directory.

  • Change to the subdirectory theme-d-intr-0.12.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.12.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.12.0/theme-d-code. See Theme-D User Guide for a description of the module search path.

Example Programs

The example programs hello, hello2, hello3, calc, and theme-d-intr-demo are located in directory /usr/share/doc/theme-d-intr/examples/theme-d-intr-examples and in directory theme-d-intr-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. 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/.