runpdftex -- a wrapper to run pdftex via a library call.

Introduction

runpdftex is a wrapper to run pdftex via a library call. The main purpose of this wrapper is to help developers to convert TeX documents to PDF using pdftex via a well-defined API. This way, TeX-specific issues can be (partly) hidden.

Example

A minimal example how runpdftex can be used is here:

#include <stdlib.h>
#include <stdio.h>
#include "runpdftex.h"

int main()
{
    runpdftex_status_t r;

    runpdftex_data_t *data = runpdftex_create();
    runpdftex_set_tex_file(data, "/home/thanh/pdftex/runptex/test/good-file.tex");
    runpdftex_set_working_dir(data, "/home/thanh/pdftex/runptex/test");
    runpdftex_add_option(data, "-fmt=pdflatex");
    runpdftex_run(data);
    r = runpdftex_get_status(data);
    if (r == RUNPDFTEX_STATUS_OK)
        puts("OK");
    else {
        fputs(runpdftex_get_status_str(data), stderr);
        fputs("\n", stderr);
    }
    runpdftex_destroy(data);

    return (r == RUNPDFTEX_STATUS_OK) ? EXIT_SUCCESS : EXIT_FAILURE;
}

Installation

• Download the sources from http://runpdftex.sarovar.org/src

• Unpack the sources

• Edit Makefile to set the location where you want to install runpdftex. By default runpdftex would be installed as follows:

- the header file runpdftex.h --> /usr/local/include
- the library file librunpdftex.a --> /usr/local/lib
- the configuration file runpdftex.cfg --> /etc/runpdftex

If you install to a location that is not searched by your compiler by default, you have to tell your compiler the paths to those files. For example, if you set the prefix in Makefile to /opt/runpdftex, then add "-I/opt/runpdftex/include" to your compiling options and "-L/opt/runpdftex/lib -lrunpdftex" or "/opt/runpdftex/lib/librunpdftex.a" to your linking options.

• run make to compile runpdftex and generate a sample configuration file. By default the path to pdftex binary is guessed using which pdftex. If this is not what you want, or this doesn't work, you need to edit runpdftex.cfg manually before running make install.

• run make install to install runpdftex to the location set in Makefile. You must have write permission to the target locations of course.

• optionally you can run make test to compile a minimal test file and run it. The expected result is that the compilation passes, but running the test file might fail if the generated configuration file doesn't fit your existing pdftex setup.

Configuration

The default location of the configuration file (runpdftex.cfg) is /etc/runpdftex, which can be altered when by editing Makefile as mentioned above, or setting an environment variable RUNPDFTEX_CFG_DIR. The syntax of the config file is trivial:

# this is the config file for runpdftex.

# 'pdftex_binary' gives the location of the pdftex binary.
pdftex_binary /path/to/your/pdftex_binary

# 'allowed_option' tells which options can be passed to runpdftex (by calling
# runpdftex_add_option())
allowed_option -fmt=pdflatex
allowed_option -fmt=pdftex

# 'default_option' tells which options are passed to pdftex by default. This is
# completely independent of 'allowed_option' mentioned above. Be careful with
# changing those options, since improper options may lead to security problems
# or failure of runpdftex. In most cases you will want pdftex to run in batch
# mode and disable shell escaping.
default_option -interaction=batchmode
default_option -no-shell-escape

API

The API of runpdftex is documented in runpdftex.h

Support

The forum to ask and discuss questions about runpdftex is available at http://sarovar.org/forum/?group_id=481

---