Troubleshooting Guide

Compilation Issues

MiniLibX Compilation Errors

Error: 'mlx.h' file not found

Symptom:

fractol.h:20:10: fatal error: minilibx-linux/mlx.h: No such file or directory
 #include "minilibx-linux/mlx.h"
          ^~~~~~~~~~~~~~~~~~~~~~

Cause: MiniLibX library not installed or incorrect path.Solution:

Step 1: Clone MiniLibX

git clone https://github.com/42Paris/minilibx-linux.git

Step 2: Verify Directory Structure

Ensure your project structure looks like:

fractol/
├── minilibx-linux/
│   ├── mlx.h
│   └── ...
├── fractol.h
├── main.c
└── Makefile

Step 3: Compile MiniLibX

cd minilibx-linux
make
cd ..

Error: Cannot find -lmlx

Symptom:

/usr/bin/ld: cannot find -lmlx
collect2: error: ld returned 1 exit status

Cause: MiniLibX library not compiled or linker cannot find it.Solution:

Compile MiniLibX:

make -C minilibx-linux

Verify libmlx.a exists:

ls minilibx-linux/libmlx.a

Check Makefile linker flags (Makefile:30):

$(CC) $(CFLAGS) -o $(NAME) $(OFILES) -L$(MINILIBX_DIR) -lmlx -lm -lX11 -lXext

The -L$(MINILIBX_DIR) flag tells the linker where to find libmlx.a.

Error: X11 Libraries Not Found

Symptom:

/usr/bin/ld: cannot find -lX11
/usr/bin/ld: cannot find -lXext

Cause: X11 development libraries not installed.Solution:On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libx11-dev libxext-dev libbsd-dev

On Fedora/RHEL:

sudo dnf install libX11-devel libXext-devel libbsd-devel

On Arch Linux:

sudo pacman -S libx11 libxext libbsd

Error: math.h Functions Undefined

Symptom:

undefined reference to 'sqrt'
undefined reference to 'pow'

Cause: Math library not linked.Solution:Verify the -lm flag is present in the Makefile (Makefile:30):

$(CC) $(CFLAGS) -o $(NAME) $(OFILES) -L$(MINILIBX_DIR) -lmlx -lm -lX11 -lXext
                                                             ^^^^

The order of libraries matters. -lm should come after object files but position relative to other -l flags is flexible.

Makefile Issues

Error: make: *** No rule to make target

Symptom:

make: *** No rule to make target 'fractol.c', needed by 'fractol.o'

Cause: Source files not found or incorrect wildcard pattern.Solution:Check the CFILES definition in Makefile:22-23:

CFILES = $(wildcard $(FRACTOL_DIR)/*.c) \
         $(wildcard $(FRACTOL_DIR)/fractals/*.c)

Verify files exist:

ls *.c
ls fractals/*.c 2>/dev/null

The wildcard function only finds files that exist at the time make is run. If you create new .c files, re-run make.

Runtime Errors

X11 Display Issues

Error: Can't open display

Symptom:

Error: Can't open display:

Cause: No X11 server running or DISPLAY environment variable not set.Solutions:Solution 1: Running via SSHIf connecting via SSH, enable X11 forwarding:

ssh -X username@hostname
./fractol Mandelbrot

Solution 2: WSL (Windows Subsystem for Linux)Install an X server for Windows:

Install VcXsrv or Xming
Launch the X server
Set DISPLAY:

export DISPLAY=:0
./fractol Mandelbrot

Solution 3: Verify DISPLAY locally

echo $DISPLAY
# Should output something like ":0" or ":1"

# If empty, set it:
export DISPLAY=:0

Error: mlx_init() Returns NULL

Symptom: Program outputs “Error with malloc” and exits immediately.Relevant Code (fractol_init.c:42-44):

fractol->mlx_connection = mlx_init();
if (fractol->mlx_connection == NULL)
	malloc_error();

Cause: MiniLibX failed to initialize (usually X11 connection issue).Solutions:

Check X11 is running:

ps aux | grep X

Test with a simple X program:

xclock &
# If xclock doesn't appear, X11 is not running properly

Check permissions:

xauth list
echo $XAUTHORITY

The error message says “malloc” but the actual issue is X11 connection failure. The malloc_error() function (fractol_init.c:15-19) is used for any initialization failure.

Memory Issues

Segmentation Fault on Startup

Possible Causes:

Null pointer dereference
Uninitialized variables
Invalid function arguments

Debugging Steps:

Step 1: Use GDB

gcc -g -Wall -Wextra -Werror *.c -L minilibx-linux -lmlx -lm -lX11 -lXext -o fractol
gdb ./fractol
(gdb) run Mandelbrot
# When it crashes:
(gdb) backtrace
(gdb) info locals

Step 2: Check NULL Returns

The initialization sequence in fractol_init.c:40-66 checks for NULL at each step:

fractol->mlx_connection = mlx_init();
if (fractol->mlx_connection == NULL)
	malloc_error();  // Line 44

fractol->mlx_window = mlx_new_window(...);
if (fractol->mlx_window == NULL)
	malloc_error();  // Line 51

fractol->img.img_ptr = mlx_new_image(...);
if (fractol->img.img_ptr == NULL)
	malloc_error();  // Line 60

If the program calls malloc_error(), the issue is in MiniLibX initialization.

Step 3: Verify Argument Parsing

Check arguments match expected format (main.c:19-20):

# Valid:
./fractol Mandelbrot
./fractol Julia -0.7 0.27015

# Invalid (causes exit):
./fractol
./fractol Julia
./fractol Mandelbrot 0.5 0.5

Memory Leaks

Detection:

valgrind --leak-check=full ./fractol Mandelbrot

Proper Cleanup:The close_handler() function (events.c:15-24) properly cleans up resources:

int	close_handler(t_fractol *fractol)
{
	mlx_destroy_image(fractol->mlx_connection,
		fractol->img.img_ptr);
	mlx_destroy_window(fractol->mlx_connection,
		fractol->mlx_window);
	mlx_destroy_display(fractol->mlx_connection);
	free(fractol->mlx_connection);
	exit(EXIT_SUCCESS);
}

Always call mlx_destroy_display() before free(mlx_connection) to avoid memory leaks in the MiniLibX library.

Cleanup Order:

Destroy images
Destroy windows
Destroy display connection
Free connection pointer

Rendering Issues

Visual Artifacts

Blank/Black Window

Possible Causes:

Image not displayed: Check mlx_put_image_to_window() is called
All pixels same color: Verify color calculation logic
Incorrect coordinates: Check map() function parameters

Verification:Add debug output in handle_pixel() (fractol_render.c:37):

void	handle_pixel(int x, int y, t_fractol *fractol)
{
	// Add this temporarily:
	if (x == 0 && y == 0)
		printf("First pixel: z=(%.2f, %.2f)\n", z.x, z.y);
	
	// ... rest of function
}

Expected output:

First pixel: z=(-2.00, 2.00)

Distorted/Stretched Fractal

Cause: Incorrect aspect ratio or coordinate mapping.Check coordinate mapping (fractol_render.c:45-46):

z.x = (map(x, -2, +2, WIDTH) * fractol->zoom) + fractol->shift_x;
z.y = (map(y, +2, -2, HEIGHT) * fractol->zoom) + fractol->shift_y;

Common mistakes:

Wrong WIDTH/HEIGHT constants
Swapped min/max in map() parameters
Missing zoom multiplication

The y-axis uses (+2, -2) instead of (-2, +2) to flip the coordinate system (screen coordinates grow downward, math coordinates grow upward).

Pixelated at High Zoom

Cause: Floating-point precision limits.Symptoms:

Fractal appears blocky at deep zoom
Detail doesn’t increase with more zoom
Occurs around zoom < 1e-13

Solutions:

Accept the limitation: Standard double has ~15 digits precision
Use specialized software: Programs like Kalles Fraktaler use arbitrary precision
Implement perturbation theory: Advanced technique for deep zooms

For most exploration, zoom levels above 1e-13 are not necessary. The interesting structures are visible at more moderate zoom levels.

Colors Don't Change

Cause: Iteration count at min/max or incorrect color mapping.Check iteration limits:

# Press + to increase iterations
# Press - to decrease iterations

If iterations = 0, all points will be white (never escape). If iterations is too low, most points escape immediately (same color).Verify color mapping (fractol_render.c:53-54):

color = map(i, PSYCHEDELIC_LIME, PSYCHEDELIC_MINT,
            fractol->iterations_definition);

Ensure i varies between 0 and iterations_definition.

Performance Issues

Very Slow Rendering

Diagnosis:Check current settings:

printf("Iterations: %d\n", fractol->iterations_definition);
printf("Zoom: %f\n", fractol->zoom);
printf("Resolution: %dx%d\n", WIDTH, HEIGHT);

Solutions:

Option 1: Reduce Iterations

Press - key repeatedly to decrease from default 30.

Effect: Faster rendering, less detail

Option 2: Lower Resolution

Edit fractol.h:24-25:

# define WIDTH   800   // was 2000
# define HEIGHT  600   // was 1500

Recompile:

make re

Effect: 6.25× faster, smaller window

Option 3: Optimize Compiler Flags

Edit Makefile:17 to add optimization:

CFLAGS = -Wall -Wextra -Werror -O3

Effect: 20-40% faster through compiler optimizations

-O3 optimization may make debugging harder. Use -O2 for a balanced approach.

Laggy Mouse/Keyboard Response

Cause: Each input event triggers a full re-render.Code responsible (events.c:42 and events.c:58):

int	key_handler(int keysym, t_fractol *fractol)
{
	// ... handle input ...
	fractol_render(fractol);  // Re-renders entire image
	return (0);
}

Solutions:

Reduce resolution: Smaller images render faster
Lower iterations: Fewer calculations per pixel
Accept the delay: Fractal rendering is computationally expensive

For development/testing, use 800×600 resolution with 20 iterations for smooth interaction. Switch to high quality for final viewing.

Argument Parsing Issues

Invalid Arguments Error

Symptom:

Please enter: 
	"./fractol Mandelbrot"
	 or
	"./fractol Julia <value_1> <value_2>"

Valid Usage:

# Mandelbrot set
./fractol Mandelbrot

# Julia set (requires 2 parameters)
./fractol Julia -0.7 0.27015
./fractol Julia 0.285 0.01
./fractol Julia -0.4 0.6

Argument Parsing (main.c:19-27):

if ((argc == 2 && !ft_strncmp(argv[1], "Mandelbrot"))
	|| (argc == 4 && !ft_strncmp(argv[1], "Julia")))
{
	fractol.name = argv[1];
	if (!ft_strncmp(fractol.name, "Julia"))
	{
		fractol.julia_x = atoi_plus(argv[2]);
		fractol.julia_y = atoi_plus(argv[3]);
	}
}

Fractal name is case-sensitive. “mandelbrot” or “MANDELBROT” will not work - use exact spelling: “Mandelbrot” or “Julia”.

Debugging Checklist

When encountering issues, check in this order:

Getting Help

If issues persist after trying these solutions:

Check compiler warnings:

make re 2>&1 | grep warning

Run with debugging:

gdb ./fractol
(gdb) run Mandelbrot
(gdb) backtrace  # After crash

Test MiniLibX separately:

cd minilibx-linux
make
./test/mlx-test  # If available

Verify system requirements:

Linux operating system
X11 window system
GCC or Clang compiler
Standard math library

MiniLibX is Linux-specific and requires X11. It will not work on macOS (use minilibx_macos instead) or Windows (requires WSL with X server).

Getting Started

User Guide

Technical Reference

Advanced

Troubleshooting Guide

Compilation Issues

MiniLibX Compilation Errors

Makefile Issues

Runtime Errors

X11 Display Issues

Memory Issues

Rendering Issues

Visual Artifacts

Performance Issues

Argument Parsing Issues

Debugging Checklist

Getting Help

Build docs developers (and LLMs) love

Getting Started

User Guide

Technical Reference

Advanced

​Compilation Issues

​MiniLibX Compilation Errors

​Makefile Issues

​Runtime Errors

​X11 Display Issues

​Memory Issues

​Rendering Issues

​Visual Artifacts

​Performance Issues

​Argument Parsing Issues

​Debugging Checklist

​Getting Help

Build docs developers (and LLMs) love

Compilation Issues

MiniLibX Compilation Errors

Makefile Issues

Runtime Errors

X11 Display Issues

Memory Issues

Rendering Issues

Visual Artifacts

Performance Issues

Argument Parsing Issues

Debugging Checklist

Getting Help