|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## Project Overview |
6 | | - |
7 | | -This is node-gd, a Node.js binding for the libgd C graphics library. It provides high-level JavaScript APIs for creating, manipulating, and saving images in various formats (PNG, JPEG, GIF, BMP, TIFF, WebP, etc.). |
8 | | - |
9 | | -## Key Architecture |
10 | | - |
11 | | -### Core Components |
12 | | - |
13 | | -- **Native C++ binding** (`src/`) - Contains the core N-API wrapper around libgd |
14 | | - - `node_gd.cc` - Main implementation with all image manipulation functions |
15 | | - - `node_gd.h` - Header file with class definitions and macros |
16 | | - - `addon.cc` - Module initialization |
17 | | - - `node_gd_workers.cc` - Async worker implementations for file I/O |
18 | | - |
19 | | -- **JavaScript wrapper** (`lib/`) - Adds convenience methods and Promise support |
20 | | - - `node-gd.js` - Main wrapper that adds format-specific convenience functions |
21 | | - - `bindings.js` - Handles the native binding loading |
22 | | - - `GifAnim.js` - Animated GIF functionality |
23 | | - |
24 | | -- **Entry point** (`index.js`) - Simple module setup that exports the main API |
25 | | - |
26 | | -### Build System |
27 | | - |
28 | | -- Uses `node-gyp` for compiling the native C++ code |
29 | | -- `binding.gyp` - Defines build configuration with conditional compilation based on available libraries |
30 | | -- `util.sh` - Shell script that detects available libgd features (AVIF, HEIF, TIFF, etc.) |
31 | | - |
32 | | -## Common Commands |
33 | | - |
34 | | -### Development |
35 | | -```bash |
36 | | -# Build the native module |
37 | | -npm run rebuild |
38 | | - |
39 | | -# Clean build artifacts |
40 | | -npm run clean |
41 | | - |
42 | | -# Install (triggers rebuild) |
43 | | -npm install |
44 | | -``` |
45 | | - |
46 | | -### Testing |
47 | | -```bash |
48 | | -# Run all tests (builds first via pretest) |
49 | | -npm test |
50 | | - |
51 | | -# Just build without testing |
52 | | -npm run pretest |
53 | | -``` |
54 | | - |
55 | | -### Docker Development |
56 | | -```bash |
57 | | -# Build Docker image |
58 | | -npm run docker-build |
59 | | - |
60 | | -# Run in Docker |
61 | | -npm run docker-run |
62 | | -``` |
63 | | - |
64 | | -## Development Notes |
65 | | - |
66 | | -### Image Types |
67 | | -- **Palette images** - Created with `gd.create()`, max 256 colors, white background |
68 | | -- **True color images** - Created with `gd.createTrueColor()`, millions of colors, black background |
69 | | - |
70 | | -### Memory Management |
71 | | -- All images must be explicitly destroyed with `image.destroy()` to free C-level memory |
72 | | -- Failing to destroy images will cause memory leaks |
73 | | - |
74 | | -### Async vs Sync |
75 | | -- Version 2.x removed sync functions (`createSync`, `createTrueColorSync`) |
76 | | -- All file I/O operations return Promises and use N-API AsyncWorkers |
77 | | -- Drawing operations are synchronous |
78 | | - |
79 | | -### Platform Support |
80 | | -- **Does not build on Windows** - explicitly excluded in package.json |
81 | | -- Requires libgd development headers to be installed on the system |
82 | | -- Uses pkg-config to find libgd |
83 | | - |
84 | | -### Testing |
85 | | -- Uses Mocha with ES modules |
86 | | -- Tests are in `test/` directory with `.test.mjs` extension |
87 | | -- Test fixtures in `test/fixtures/` |
88 | | -- Output images saved to `test/output/` |
89 | | - |
90 | | -### Conditional Features |
91 | | -The build system detects available libgd features and compiles accordingly: |
92 | | -- AVIF support (requires libavif) |
93 | | -- HEIF support (requires libheif) |
94 | | -- TIFF support (requires libtiff) |
95 | | -- WebP support (requires libwebp) |
96 | | -- FreeType font support |
97 | | -- Fontconfig support |
98 | | - |
99 | | -Check available features with `gd.getGDVersion()` and feature flags like `gd.GD_TIFF`. |
| 3 | +Guidance for Claude Code. See `AGENTS.md` for the consolidated, up-to-date repo instructions. |
0 commit comments