Setup Guide for ttf-parser-node

Step-by-Step Installation

1. Prerequisites

First, ensure you have the required tools installed:

Install Rust (if not already installed)

Linux/macOS:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Windows: Download and run: https://rustup.rs/

Verify installation:

rustc --version
cargo --version

Install Node.js (if not already installed)

Download from: https://nodejs.org/ (LTS version recommended)

Verify installation:

node --version
npm --version

2. Project Setup

Navigate to your project directory and install dependencies:

cd ttf-parser-node
npm install

3. Build the Native Module

Build in release mode (recommended):

npm run build

Or build in debug mode for development:

npm run build-debug

This will:

1. Compile the Rust code to a native Node.js addon
2. Generate index.node in your project directory

4. Test the Installation

Run the test script:

# With default system font
npm test

# Or specify a font file
node test.js /path/to/your/font.ttf

Quick Start Example

Create a new file example.js:

const Font = require('./index.js');

// Load a font
const font = Font.fromFile('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf');

// Print basic info
console.log('Font Family:', font.familyName);
console.log('Glyphs:', font.numberOfGlyphs);
console.log('Units per EM:', font.unitsPerEm);

// Get info for character 'A'
const glyphId = font.glyphIndex('A');
console.log('Glyph ID for "A":', glyphId);

const advance = font.glyphHorAdvance(glyphId);
console.log('Advance width:', advance);

Run it:

node example.js

Common Issues and Solutions

Issue: "Cannot find module './index.node'"

Solution: Build the native module first:

npm run build

Issue: "cargo: command not found"

Solution: Install Rust or ensure cargo is in your PATH:

source $HOME/.cargo/env  # Linux/macOS

Issue: Build fails with linker errors

Solution:

• Linux: Install build essentials:

  sudo apt-get install build-essential

• Windows: Install Visual Studio Build Tools
• macOS: Install Xcode command line tools:

  xcode-select --install

Issue: "Failed to parse font"

Solution: Ensure:

1. The file path is correct
2. The file is a valid TrueType/OpenType font
3. You have read permissions for the file

Using in Your Own Project

Option 1: Copy Files

Copy these files to your project:

• index.js (JavaScript wrapper)
• index.node (compiled native module)
• package.json (dependencies)

Then in your code:

const Font = require('./path/to/ttf-parser-node');

Option 2: Publish as npm Package

1. Update package.json with your details
2. Ensure .gitignore excludes index.node and target/
3. Users will need to build locally or you can publish pre-built binaries

Option 3: Local npm Link

# In ttf-parser-node directory
npm link

# In your project directory
npm link ttf-parser-node

Development Workflow

Making Changes to Rust Code

1. Edit src/lib.rs
2. Rebuild:

   npm run build

3. Test your changes:

   node test.js

Adding New Functions

1. Add Rust function in src/lib.rs:

   fn my_new_function(mut cx: FunctionContext) -> JsResult<JsNumber> {
       // Your Rust code here
       Ok(cx.number(42.0))
   }

2. Export in main function:

   cx.export_function("myNewFunction", my_new_function)?;

3. Add JavaScript wrapper in index.js:

   myNewFunction() {
       return addon.myNewFunction(this.buffer);
   }

4. Rebuild and test:

   npm run build
   node test.js

Performance Tips

1. Reuse Font instances - Parsing is fast but not free
2. Batch operations - Use getAllAdvances() instead of calling glyphHorAdvance() repeatedly
3. Cache glyph IDs - If you're measuring the same text repeatedly
4. Use release builds - They're significantly faster than debug builds

Next Steps

• Read the full README.md for API documentation
• Check out the ttf-parser documentation for more features to expose
• Explore adding glyph outline extraction, font subsetting, etc.

Getting Help

If you encounter issues:

1. Check this guide and README.md
2. Verify your Rust and Node.js installations
3. Try with a simple, known-good font file (like DejaVu Sans)
4. Check the ttf-parser repository for known issues

Resources

• ttf-parser GitHub
• Neon Bindings
• Rust Book
• TrueType Specification