Leptonica Tutorial – Environment setup

Leptonica Development with Eclipse

This is the first one of few tutorials that I am writring on using Leptonica image processing library

Before we start let’s give credit where the credit is due, and this is goes out to Jay W.(need link) on which this instructions are largely based on.


  • Eclipse
  • MinGW
  • Leptonica

I assume that you have installed and configured Eclipse CDT ( plugging for C/C++ development, as well as MinGW and can run simple c++ hello world using make file.


1. Lets start by downloading latest leptonica library from Leptonica download site
and extract the library into your lib directory I use E:/source/c-libraries/leptonica-1.68

2. This is probably the most complicated part of the setup, configuring the Eclipse environment and compiling Leptonica hello world project.

1. Lets start by ‘Creating new C++ Make Project’ and naming it ‘HelloWorldLeptonica’ in Eclipse, before continuing lets make sure we can compile and run the project.
2. Now we will edit Properties for our newly created project, navigate to Properties->C/C++ Build -> Environment
and add new property LEPT_HOME

LEPT_HOME E:/source/c-libraries/leptonica-1.67

Include/Library Configuration

Navigate to Properties->C/C++ General -> Paths and Symbols and select Include Tab -> GNU-C++
and add new Include directory ‘E:/source/c-libraries/leptonica-1.67/include’, this will allow us to browse includes from within Eclipse.

Now lets copy leptonlib.dll from ‘E:/source/c-libraries/leptonica-1.67/lib’ into our project directory.
this way we can run the project directly from Eclipse.

Makefile Configuration

I will highlight main sections that need to be configured, this is where we use our previously defined variable ‘LEPT_HOME’ come into play.

  • Include Files – INCS
  • Libraries – LIBS
  • Compiler Flags – CFLAGS

We need to make sure to include header files and leptonica library.

INCS		=	-I$(LEPT_HOME)/include		
LIBS		=	-L$(LEPT_HOME)/lib		\

Capital flag -L indicates to includes $(LEPT_HOME)/lib directory in the search path, while lowercase -l indicates what library to load, if we wanted to include debug version we would use -lleptonlibd

Here is a make file used by the demo project

CFLAGS =	-O2 -g -Wall -fmessage-length=0
CPP         =   g++
OBJS		=	HelloWorldLeptonica.o
INCS		=	-I$(LEPT_HOME)/include		
LIBS		=	-L$(LEPT_HOME)/lib		\
PROJECT =	HelloWorldLeptonica.exe
all: $(PROJECT)
	@echo Linking $(OUTPUT)
	@echo Completed building $(OUTPUT)
	@echo Cleaning $(PROJECT)
-include $(OBJS:.o=.d)
%.o:	%.cpp
	@echo Compiling $<
	@$(CPP) $(CFLAGS) -c $(INCS) -o $*.o $*.cpp
	@$(CPP) -MM $(CFLAGS) $(INCS) $*.cpp > $*.d
%.o:	%.c
	@echo Compiling $<
	@$(CC) $(CFLAGS) -c $(INCS) -o $@ $<
	@$(CC) -MM $(CFLAGS) $(INCS) $*.c > $*.d


As always we want to start with something simple so here is it, we get current directory and read in file a ‘test.png’ file, if all went well
we display image dimensions.

 * Leptonica Hello World
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <sys/param.h>
#include <unistd.h>
#   include <leptonica/allheaders.h>
int main(void) {
	printf("\nTesting Leptonica Setup \n");
	// Read test.png from current working directory
	char* filename = NULL;
	filename = getcwd(filename, MAXPATHLEN);
	strcat(filename, "\\test.png");
	PIX* pix = pixRead(filename);
	if (!pix) {
		printf("Error opening file");
		return 1;
	printf("Image width : %d", pix->w);
	return 0;

If we want to build the project from outside of Eclipse you will have to define the the make file environmental variable in make file directly


g++ and Eclipse debugging hint

In am not an expert in c++ in any way so this can be totally wrong, but in order to get the debugger to work in eclipse
the Compiler Flags (CFLAGS) need to be using -g -O0 instead of the default one -O2 -g.
If we don’t do this then Eclipse complains that it can’t find the source when it hits a breakpoint.

Download HelloWorldLeptonica Eclipse Project from here HelloWorldLeptonica

At this point you should be ready to compile and run/debug leptonica project from within Eclipse IDE.

As always comments and corrections are always welcome.

9 thoughts on “Leptonica Tutorial – Environment setup

  1. Just saw this — seems like a useful project 🙂

    Couple of suggestions:
    * use the most recent version, 1.69
    * in C, leptonica has typedefs for structs (e.g., PIX) to avoid having to type “struct” everywhere, but in C++, you can declare the struct without using the struct (or class) keyword (e.g., Pix).

    If you have any questions, please don’t hesitate to ask.

  2. Dear sir,
    I an trying this program in mac lion in eclipse.But i an unable to run this program.
    I am also try following command but not work.

    g++ HelloWorldLeptonica.cpp -o HelloWordLeptonica -I /opt/local/include/leptonica -L /opt/local/lib

    please help me. i am beginner with leptonica. please help me and thanks in advance

  3. when i run above command

    Undefined symbols for architecture x86_64:
    “_boxCreate”, referenced from:
    _main in ccTnaV0p.o
    “_pixClipRectangle”, referenced from:
    _main in ccTnaV0p.o
    “_pixDestroy”, referenced from:
    _main in ccTnaV0p.o
    “_pixRead”, referenced from:
    _main in ccTnaV0p.o
    ld: symbol(s) not found for architecture x86_64
    collect2: ld returned 1 exit status

  4. Dear sir
    I fix all problems but still 2 errors remains. first is library not found for -lleptonlib and another is make: ***[HelloWorldLeptonica.exe] errer 1.

    please help me as soon as possible. Thanks in advance

Leave a Reply

Your email address will not be published. Required fields are marked *

* Copy This Password *

* Type Or Paste Password Here *