<?xml version="1.0"?>
<!DOCTYPE doc [ <!ENTITY IntrFormat SYSTEM "intr-format.xml">
                <!ENTITY IntrExample1 SYSTEM "intr-example1.xml">
                <!ENTITY IntrExample2 SYSTEM "intr-example2.xml">
                <!ENTITY IntrBuild SYSTEM "intr-build.xml"> ]>
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  <articleinfo>
    <title>
      Theme-D-Intr User Manual
    </title>
    <author>
      <personname>
        <firstname>
          Tommi
        </firstname>
        <surname>
          Höynälänmaa
        </surname>
      </personname>
    </author>
    <copyright>
      <year>
        2020-2025
      </year>
      <holder>
        Tommi Höynälänmaa
      </holder>
    </copyright>
    <legalnotice>
      <para>
        This file is part of Theme-D-Intr version 0.20.4. This document has
        been last updated December 5, 2025.
      </para>
      <para>
        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.
      </para>
      <para>
        See file
        <filename>
          doc/GFDL-1.3
        </filename>
        in the source code
        package for the license.
      </para>
    </legalnotice>
  </articleinfo>
  <section>
    <title>
      Introduction
    </title>
    <para>
      Theme-D-Intr is a software library allowing the use of the
      introspected GObject modules in Theme-D.
    </para>
  </section>
  <section>
    <title>
      Installation
    </title>
    <section>
      <title>
        Debian forky (testing) and sid (unstable) and Ubuntu Resolute
      </title>
      If you use the Synaptic Package Manager install the packages
      <filename>theme-d-intr</filename>
      and
      <filename>theme-d-intr-dev</filename>
      . If you want to install
      the example programs install one or both of the packages
      <filename>theme-d-intr-gtk3-examples</filename>
      and
      <filename>theme-d-intr-gtk4-examples</filename>.
      In order to install the packages from the command line give
      command
      <programlisting>
        sudo apt install theme-d-intr theme-d-intr-dev
      </programlisting>
      and optionally one or both of the commands
      <programlisting>
        sudo apt install theme-d-intr-gtk3-examples
        sudo apt install theme-d-intr-gtk4-examples
      </programlisting>
    </section>
    <section>
      <title>
        Other Debian-based Systems
      </title>
      <itemizedlist>
        <listitem>
          Install Guile 3.0 is you don't have it already.
        </listitem>
        <listitem>
          Install Theme-D version 7.2.3 is you don't have it already.
          See
          <ulink url="https://www.iki.fi/tohoyn/theme-d/theme-d-user-guide-7.2.3.pdf">Theme-D User Guide</ulink>
          for instructions.
        </listitem>
        <listitem>
          Install G-Golf. See
          <ulink url="http://www.iki.fi/tohoyn/g-golf-debian/">http://www.iki.fi/tohoyn/g-golf-debian/</ulink>.
        </listitem>
        <listitem>
          Create a directory for the build and download packages
          <filename>theme-d-intr-0.20.4.tar.xz</filename>
          and
          <filename>theme-d-intr_0.20.4-1.debian.tar.xz</filename>
          there.
        </listitem>
        <listitem>
          Execute the following commands
          &IntrBuild;
          in the directory.
        </listitem>
        <listitem>
          Give command <code>cd ..</code> and install the packages with commands
          <programlisting>
            sudo dpkg -i theme-d-intr_0.20.4-1_ARCH.deb
            sudo dpkg -i theme-d-intr-dev_0.20.4-1_all.deb
          </programlisting>
          The architecture ARCH can be computed by
          <programlisting>
            dpkg-architecture -q DEB_HOST_ARCH
          </programlisting>
          You can install the example programs by installing one or
          both of the packages
          <filename>theme-d-intr-gtk4-examples_0.20.4-1_all.deb</filename>
          and
          <filename>theme-d-intr-gtk3-examples_0.20.4-1_all.deb</filename>.
        </listitem>
        <listitem>
          Ensure that your Guile installation file
          <filename>~/.guile</filename>
          contains the following lines:
          <programlisting>
            (use-modules (oop goops))
            (default-duplicate-binding-handler
              '(merge-generics replace warn-override-core warn last))
          </programlisting>
        </listitem>
      </itemizedlist>
    </section>
    <section>
      <title>
        Other UNIX Systems
      </title>
      <itemizedlist>
        <listitem>
          <para>
            Install the G-Golf library. See
            <ulink url="https://www.gnu.org/software/g-golf/install.html">
              https://www.gnu.org/software/g-golf/install.html
            </ulink>
            .
          </para>
        </listitem>
        <listitem>
          <para>
            Unpack package
            <filename>theme-d-intr-0.20.4.tar.xz</filename>
            into
            some directory.
          </para>
        </listitem>
        <listitem>
          <para>
            Change to the subdirectory
            <filename>theme-d-intr-0.20.4</filename>
            and give commands
            <programlisting>
              ./configure
              make
              sudo make install-complete
            </programlisting>
          </para>
        </listitem>
        <listitem>
          Ensure that your Guile installation file
          <filename>~/.guile</filename>
          contains the following lines:
          <programlisting>
            (use-modules (oop goops))
            (default-duplicate-binding-handler
              '(merge-generics replace warn-override-core warn last))
          </programlisting>
        </listitem>
      </itemizedlist>
    </section>
  </section>
  <section>
    <title>
      Using Theme-D-Intr without Installing
    </title>
    <para>
      It is possible to use the software without installing it.
      First give the following commands in the subdirectory
      <filename>theme-d-intr-0.20.4</filename>:
      <programlisting>
        ./configure
        make
      </programlisting>
      Modify the file
      <filename>~/.guile</filename>
      as in a normal
      installation (see the previous section).
      Now you can launch the uninstalled environment by giving command
      <programlisting>
        ./uninstalled-env bash
      </programlisting>
      in subdirectory
      <filename>meta</filename>.
      You also have to take care that the Theme-D module search path
      (option
      <code>-m</code> or <code>-M</code>
      for the Theme-D compiler and linker)
      contains the directory
      <filename>xxx/theme-d-intr-0.20.4/theme-d-code</filename>.
      See Theme-D User Guide
      for a description of the module search path.
    </para>
  </section>
  <section>
    <title>
      Example Programs
    </title>
    <para>
      It is recommended that you copy the example programs into your home
      directory for building them.
      If you have installed Theme-D-Intr normally go to directory
      <filename>/usr/share/doc/theme-d-intr-gtk4-examples</filename>.
      If you use Theme-D-Intr without installed it go to the subdirectory
      <filename>examples</filename> in the source code.
      Give command
      <programlisting>
        cp -avi intr-gtk4-examples MYDIR
      </programlisting>
      where <filename>MYDIR</filename> is the directory where you want to
      install the programs.
      Then, go to the directory
      <filename>/usr/share/doc/theme-d-intr-gtk3-examples</filename> or
      <filename>examples</filename> and give command
      <programlisting>
        cp -avi intr-gtk3-examples MYDIR
      </programlisting>
    </para>
    <para>
      The example programs
      <filename>appwindow</filename>,
      <filename>hello</filename>,
      <filename>hello2</filename>,
      <filename>hello3</filename>,
      <filename>calc</filename>,
      <filename>calc2</filename>,
      <filename>custom-layout-example</filename>,
      <filename>flag-demo</filename>, and
      <filename>theme-d-intr-demo</filename>
      for GTK 4 are located in
      directory
      <filename>/usr/share/doc/theme-d-intr-gtk4-examples/intr-gtk4-examples</filename>
      and in directory
      <filename>examples/intr-gtk4-examples</filename>
      in the source package.
      You can build the example programs with command
      <code>
        make -f user.mk
      </code>
      and run them with command
      <programlisting>
        GUILE_LOAD_PATH=../..:$GUILE_LOAD_PATH run-theme-d-program &#x5c;
        &lt;program-name&gt;
      </programlisting>
      where
      <code>&lt;program-name&gt;</code>
      is the name of the
      target
      <filename>.go</filename>
      file of the program
      (<filename>main.go</filename>
      or
      <filename>run-demo.go</filename>).
      For program
      <filename>hello</filename>
      the command is
      <programlisting>
        GUILE_LOAD_PATH=.:$GUILE_LOAD_PATH run-theme-d-program hello.go
      </programlisting>
      Example program
      <filename>intr-gtk4-examples/calc2</filename>
      is linked modularly and it shall be run with command
      <programlisting>
        run-theme-d-program-m -g ../..: main.go
      </programlisting>
      or in uninstalled mode
      <programlisting>
        run-theme-d-program-m -g ../..:../../../theme-d-code: main.go
      </programlisting>
      Before you run it you have to install its configuration files with command
      <programlisting>
        ./install-calc2.sh
      </programlisting>
      If you have a Debian-based Linux operating system you have to
      ensure that packages
      <filename>gir1.2-gtk-4.0</filename>
      and
      <filename>gir1.2-adw-1</filename>
      are installed in your system.
    </para>
    <para>
      The example programs
      <filename>hello</filename>,
      <filename>hello2</filename>,
      <filename>hello3</filename>,
      <filename>calc</filename>, and
      <filename>theme-d-intr-demo</filename>
      for GTK 3 are located in
      directory
      <filename>/usr/share/doc/theme-d-intr-gtk3-examples/intr-gtk3-examples</filename>
      and in directory
      <filename>examples/intr-gtk3-examples</filename>
      in the source package.
      You can build the example programs with command
      <code>make -f user.mk</code>
      and run them with command
      <programlisting>
        GUILE_LOAD_PATH=../..:$GUILE_LOAD_PATH run-theme-d-program &#x5c;
          &lt;program-name&gt;
      </programlisting>
      where
      <code>&lt;program-name&gt;</code>
      is the name of the
      target
      <filename>.go</filename>
      file of the program
      (<filename>main.go</filename>
      or
      <filename>run-demo.go</filename>).
      For program
      <filename>hello</filename>
      the command is
      <programlisting>
        GUILE_LOAD_PATH=.:$GUILE_LOAD_PATH run-theme-d-program hello.go
      </programlisting>
      If you have a Debian-based Linux operating system you have to
      ensure that package
      <filename>gir1.2-gtk-3.0</filename>
      is installed in your system.
    </para>
  </section>
  <section>
    <title>
      Writing Programs using Theme-D-Intr
    </title>
    <para>
      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
      <filename>intr-imports.scm</filename>.
      Its format is:
      &IntrFormat;
      Namespace is the library where the definitions are imported,
      such as
      <varname>Gtk</varname>.
      Class names are given in
      format
      <varname>MyClassName</varname>.
      Note that the namespace is not
      included in the class or function name
      (<varname>Widget</varname>
      instead of
      <varname>GtkWidget</varname>).
      Methods belonging to a class
      are imported automatically when the class is imported and they
      must not be listed in the
      <varname>functions</varname>
      section. Rejected methods are generic function names for which
      we do not generate methods. There are two main reasons for
      rejecting a method:
      <itemizedlist>
        <listitem>
          <para>
            The method name overlaps a nongeneric function name,
            e.g.
            <function>append</function>.
          </para>
        </listitem>
        <listitem>
          <para>
            The methods of some name violate the covariance rule, see
            <ulink url="https://www.iki.fi/tohoyn/theme-d/theme-d-language-manual-7.2.3.pdf">Theme-D Language Manual</ulink>.
          </para>
        </listitem>
      </itemizedlist>
      The purpose of
      <varname>overridden-functions</varname>
      is to
      handle functions overridden in G-Golf. The argument types, the
      result type and the attributes are given in Theme-D format.
      The
      <varname>version</varname>
      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
      <varname>strip-boolean-result</varname>.
      See
      G-Golf documentation for this feature.
      Form
      <varname>ignore-slots</varname>
      can be used to prevent code generation for some specific slots.
      For example,
      <code>(ignore-slots (Gtk Label) xalign yalign)</code>.
      Here is an example import file:
      &IntrExample1;
      and here is another:
      &IntrExample2;
    </para>
    <para>
      The following three files are generated from the definition file:
      <itemizedlist>
        <listitem>
          <para>
            Interface file
            <filename>_intr-imports.thi</filename>
          </para>
        </listitem>
        <listitem>
          <para>
            Body file
            <filename>_intr-imports.thb</filename>
          </para>
        </listitem>
        <listitem>
          <para>
            Target module
            <filename>_intr-imports-target.scm</filename>
          </para>
        </listitem>
      </itemizedlist>
      The program and modules using G-Golf should import the
      module
      <filename>_intr-imports</filename>.
      In case you have a multiple
      part program name, such as
      <varname>(myexamples myprogram)</varname>,
      module
      <varname>_intr-imports</varname>
      has a multiple part name too,
      e.g.
      <varname>(myexamples _intr-imports)</varname>.
      File
      <filename>_intr-imports-target.scm</filename>
      is used by the
      linked program to provide access to the introspected libraries.
    </para>
    <para>
      The following commands are used to generate Theme-D-Intr files:
      <itemizedlist>
        <listitem>
          <para>
            <filename>generate-intr-interface</filename>
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>generate-intr-body</filename>
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>generate-intr-target-module</filename>
          </para>
        </listitem>
      </itemizedlist>
      If you use a multiple part program name you must give
      the
      <option>-m</option>
      option for these commands.
      The option argument is the imports module name for the first two
      commands, e.g.
      <option>-m "(myexamples _intr-imports)"</option>
      and the
      setter module name for the fourth command, e.g.
      <option>-m "(myexamples _intr-imports-target)"</option>.
      If you want to generate accessor methods
      <code>NAMESPACE-CLASS-get-SLOT</code>
      and
      <code>NAMESPACE-CLASS-set-SLOT!</code>
      use option <option>--generate-accessors</option> for all of these
      programs. Note that you can access slots without accessor methods by using
      procedures <code>slot-ref</code> and <code>slot-set!</code>.
    </para>
    <para>
      When you link a program using Theme-D-Intr you have to give the
      following options to the Theme-D linker:
      <itemizedlist>
        <listitem>
          <para>
            <option>-x "(g-golf)"</option>
          </para>
        </listitem>
        <listitem>
          <para>
            <option>-x "(guile-theme-d-intr support)"</option>
          </para>
        </listitem>
        <listitem>
          <para>
            <option>-x "&lt;target-module&gt;"</option>
          </para>
        </listitem>
        <listitem>
          <para>
            <option>--duplicates="merge-generics replace warn-override-core warn last"</option>
          </para>
        </listitem>
      </itemizedlist>
      Here
      <option>&lt;target-module&gt;</option>
      is the Theme-D name of
      the generated target module. For a program with a single part
      name it is
      <varname>(_intr-imports-target)</varname>.
      If you use the
      extra support module give also option
      <option>-x "(guile-theme-d-intr support2-gtk3)"</option>
      or
      <option>-x "(guile-theme-d-intr support2-gtk4)"</option>.
    </para>
    <para>
      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
      <filename>gir1.2-gtk-3.0</filename>
      (for GTK 3.0) or
      <filename>gir1.2-gtk-4.0</filename>
      (for GTK 4.0)
      in your system.
    </para>
    <para>
      See also the
      <filename>user.mk</filename>
      makefiles of the
      example programs.
      Example program
      <filename>hello</filename>
      has a single part program name and
      the other example programs multiple part program names.
    </para>
    <para>
      When you run programs using Theme-D-Intr the environment
      variable
      <envar>GUILE_LOAD_PATH</envar>
      has to contain the root
      directory of your program. If you use a single part
      program name this is the directory of your program.
    </para>
  </section>
  <section>
    <title>
      Distributing Programs using Theme-D-Intr
    </title>
    <para>
      If you use a Debian-based operating system the following
      packages are required to run compiled (built) Theme-D programs
      using Theme-D-Intr:
      <itemizedlist>
        <listitem>
          <filename>theme-d-rte</filename>
        </listitem>
        <listitem>
          <filename>th-scheme-utilities</filename>
        </listitem>
        <listitem>
          <filename>libthemedsupport</filename>
        </listitem>
        <listitem>
          <filename>theme-d-intr</filename>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      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
      <filename>support.scm</filename>
      from the Theme-D-Intr source package.
      If you use files
      <filename>support2-gtk3.scm</filename>
      or
      <filename>support2-gtk4.scm</filename>
      you need distribute that, too.
      These files have to be installed in subdirectory
      <filename>guile-theme-d-support</filename>
      somewhere in the
      Guile library search path. In UNIX systems this path usually
      contains directory
      <filename>/usr/share/guile/site/3.0/</filename>
      or
      <filename>/usr/share/guile/site/2.2/</filename>.
    </para>
  </section>
  <section>
    <title>
      Help with callback types
    </title>
    <para>
      You can use command
      <filename>describe-cb-type</filename>
      to get the Theme-D name and Theme-D procedure type of a callback type.
      The syntax of the command is
      <programlisting>
        describe-cb-type library callback-name [version]
      </programlisting>
      Argument
      <code>library</code>
      is the library where the callback is defined.
      Argument
      <code>callback-name</code>
      is the name of the callback type.
      Optional argument
      <code>version</code>
      is the version of the library.
      Here is an example:
      <programlisting>
        describe-cb-type Gtk CustomMeasureFunc 4.0
      </programlisting>
    </para>
  </section>
</article>
