Loading external LaTeX packages and classes in Java

Extend LaTeX document compilation capabilities by incorporating external macro packages (`.sty`) and custom document classes (`.cls`) using Aspose.TeX for Java. Resolve package dependencies dynamically from local file system directories, compressed ZIP archives, or custom memory streams without needing a full TeX Live or MiKTeX installation.

When compiling LaTeX documents containing commands like \usepackage{custompackage} or \documentclass{customclass}, the engine searches for corresponding .sty or .cls files using the configured IInputWorkingDirectory instances.

Here are the next package resolution sources:

For loading company-standard template files (.sty/.cls) stored in local folders use Local Directory as a package provider and InputFileSystemDirectory Class.
For the single-file distribution containing main TeX files alongside all necessary package dependencies use ZIP Archive as a package provider and InputZipDirectory Class.
For the high-performance execution with pre-loaded, heavily used package sets built into a .fmt file. use Pre-compiled Format as a package provider and TeXConfig.customFormat().

Load external packages from a local folder

Specify a local directory containing custom style files (.sty) or class definitions (.cls) as the input working directory for package lookup.

import com.aspose.tex.*;
import java.io.ByteArrayInputStream;
import java.nio.charset.StandardCharsets;

public class LoadExternalPackagesFromFileSystem {
    public static void main(String[] args) throws Exception {
        // Step 1: LaTeX source referencing a custom package 'companylayout.sty'
        String latexCode = "\\documentclass{article}\n" +
                           "\\usepackage{companylayout}\n" + // Custom external package
                           "\\begin{document}\n" +
                           "\\customHeader{Monthly Financial Report}\n" +
                           "Document compiled using external style package.\n" +
                           "\\end{document}";

        ByteArrayInputStream inputStream = new ByteArrayInputStream(latexCode.getBytes(StandardCharsets.UTF_8));

        // Step 2: Initialize LaTeX conversion options
        TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());

        // Step 3: Set input working directory pointing to folder where 'companylayout.sty' resides
        options.setInputWorkingDirectory(new InputFileSystemDirectory("C:/TeXProject/CustomPackages/"));

        // Step 4: Set output working directory for compiled PDF
        options.setOutputWorkingDirectory(new OutputFileSystemDirectory("C:/TeXProject/Output/"));

        // Step 5: Run compilation job
        TeXJob job = new TeXJob(inputStream, new PdfDevice(), options);
        job.run();

        System.out.println("LaTeX document compiled successfully using external .sty package.");
    }
}

Load packages and classes from a compressed ZIP archive

Package .tex source files, custom .sty packages, and images into a .zip archive, and instruct Aspose.TeX to resolve package dependencies directly from the compressed archive.

import com.aspose.tex.*;
import java.io.FileInputStream;

public class LoadExternalPackagesFromZip {
    public static void main(String[] args) throws Exception {
        // Step 1: Initialize options for LaTeX format
        TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());

        // Step 2: Open ZIP archive containing 'main.tex' and dependent '.sty'/'.cls' files
        FileInputStream zipStream = new FileInputStream("C:/TeXProject/TemplateBundle.zip");
        options.setInputWorkingDirectory(new InputZipDirectory(zipStream, "packages_subfolder"));

        // Step 3: Configure output working directory
        options.setOutputWorkingDirectory(new OutputFileSystemDirectory("C:/TeXProject/Output/"));

        // Step 4: Execute compilation job
        TeXJob job = new TeXJob("main", new PdfDevice(), options);
        job.run();

        zipStream.close();
        System.out.println("LaTeX document and external packages loaded from ZIP archive successfully.");
    }
}

Handling missing or standard TeX packages

Aspose.TeX for Java includes built-in implementations of popular core LaTeX packages (such as graphicx, amsmath, amsfonts, color, and geometry). For non-standard or third-party packages, ensure the corresponding .sty files are placed within the active IInputWorkingDirectory.

import com.aspose.tex.*;
import java.io.ByteArrayInputStream;
import java.nio.charset.StandardCharsets;

public class StandardLaTeXPackagesDemo {
    public static void main(String[] args) throws Exception {
        // Standard packages like amsmath and graphicx are processed natively
        String latexCode = "\\documentclass{article}\n" +
                           "\\usepackage{amsmath}\n" +
                           "\\usepackage{graphicx}\n" +
                           "\\begin{document}\n" +
                           "\\equation: e^{i\\pi} + 1 = 0\n" +
                           "\\end{document}";

        ByteArrayInputStream inputStream = new ByteArrayInputStream(latexCode.getBytes(StandardCharsets.UTF_8));

        TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());
        options.setOutputWorkingDirectory(new OutputFileSystemDirectory("C:/TeXProject/Output/"));

        TeXJob job = new TeXJob(inputStream, new PdfDevice(), options);
        job.run();

        System.out.println("Document with standard LaTeX packages rendered successfully.");
    }
}

Installation and Setup

Integrate Aspose.TeX for Java into your project using Maven:

Package Manager Console Command

<repository>
    <id>AsposeJavaAPI</id>
    <name>Aspose Java API</name>
    <url>https://repository.aspose.com/repo/</url>
</repository>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-tex</artifactId>
    <version>Latest</version>
</dependency>

Next Steps

FAQ

1. How does Aspose.TeX find external .sty and .cls files?

When the LaTeX engine encounters \usepackage{name} or \documentclass{name}, it looks for name.sty or name.cls in the directory provided to TeXOptions.setInputWorkingDirectory().

2. Can I use complex macro packages like TikZ or PSTricks?

Aspose.TeX supports a broad range of macro evaluation features. Packages relying on native ObjectTeX extensions or supported drawing primitives are evaluated directly; for standalone figure output, PngFigureRenderer or SvgFigureRenderer can also be used.

3. Can I pre-load heavy packages to speed up batch document processing?

Yes. You can create a custom TeX format file (.fmt) containing pre-compiled macro packages and load it via TeXConfig.customFormat() to significantly reduce per-document execution overhead.