Skip to content

Latest commit

 

History

History
341 lines (260 loc) · 9.84 KB

installation.md

File metadata and controls

341 lines (260 loc) · 9.84 KB

Installation & Setup Guide

Setup guide for Reflaxe.Elixir development with lix package management and dual-ecosystem workflows.

⚠️ Having trouble with tests or compilation? See the troubleshooting section below.

Prerequisites

Required Software

  • Node.js 16+ - For lix package management and npm scripts
  • Elixir 1.14+ - For Phoenix/Ecto ecosystem and generated code testing
  • Git - For repository cloning and dependency management

Installation Check

# Verify prerequisites
node --version    # Should be 16.0.0 or higher
elixir --version  # Should be 1.14.0 or higher
git --version     # Any recent version

Step-by-Step Installation

1. Clone Repository

git clone <repository-url>
cd reflaxe.elixir

2. Install Haxe Development Environment

Install lix Package Manager

# Install all Node.js dependencies (including lix)
npm install

This automatically installs:

  • lix - Modern Haxe package manager
  • Local project dependencies for build orchestration

Verify lix Installation

# Check lix is available
npx lix --version

# Check Haxe is available
haxe --version

# If `haxe` is not on your PATH, use the project-local shim (provided by `lix` + `.haxerc`):
./node_modules/.bin/haxe --version

Expected Output:

Haxe Compiler 4.3.7

3. Install Haxe Dependencies

# Download the pinned toolchain + libraries (per `.haxerc` + `haxe_libraries/*.hxml`)
npx lix download

This ensures the compiler/test/example dependencies are available (for example tink_macro, tink_parse, and other tink_* libs).

4. Install Elixir Dependencies

# Install Phoenix, Ecto, and other Elixir dependencies
mix deps.get

5. Verify Complete Installation

# Run comprehensive test suite
npm test

This should complete without failures.

6. Source Mapping (Experimental)

Reflaxe.Elixir has a source mapping design (to map generated .ex back to .hx), but it is currently experimental and not fully wired end‑to‑end in the AST pipeline.

See docs/04-api-reference/SOURCE_MAPPING.md for the current status and next steps.

Understanding the Setup

Why lix Instead of Global Haxe?

❌ Traditional Haxe Installation Problems:

  • Global Haxe versions cause "works on my machine" issues
  • Different projects need different Haxe versions
  • Library version conflicts between projects
  • Manual dependency management

✅ lix Package Manager Benefits:

  • Project-specific Haxe versions defined in .haxerc
  • Locked dependency versions in haxe_libraries/
  • GitHub + haxelib sources for latest libraries
  • Zero global conflicts between projects

Key Files Created by Setup

.haxerc

{
  "version": "4.3.7",
  "resolveLibs": "scoped"
}

Pins the Haxe compiler version and enables scoped library resolution for lix.

haxe_libraries/*.hxml

Pins Haxe library versions and classpaths for reproducible builds (managed by lix).

package.json Scripts

{
  "scripts": {
    "test": "npm test",
    "test:quick": "npm run test:quick",
    "test:examples": "npm run test:examples"
  }
}

Using Haxe After Installation

Use haxe (system or project-local)

This repo uses lix to manage the Haxe toolchain (via .haxerc) and Haxe libraries (via haxe_libraries/*.hxml). Use either a normal haxe install on your PATH or the lix-provided shim at ./node_modules/.bin/haxe.

# ✅ Correct
haxe build.hxml
haxe --version

# ✅ Also correct (lix shim)
./node_modules/.bin/haxe build.hxml
./node_modules/.bin/haxe --version

Compilation Examples

# Compile a simple example
cd examples/01-simple-modules
haxe BasicModule.hxml

# Run full tests
npm test

Source Mapping (Experimental)

Reflaxe.Elixir’s source mapping design (mapping generated .ex back to .hx) is currently experimental and not yet fully wired end‑to‑end in the AST pipeline.

See docs/04-api-reference/SOURCE_MAPPING.md for the current status and next steps.

Development Workflow

With File Watching (Recommended)

# 1. Start file watcher
mix haxe.watch

# 2. Make changes to Haxe files
vim src_haxe/MyModule.hx
# Files automatically recompile

# 3. Debug compile errors
mix haxe.errors --format json

Manual Compilation

# 1. Make changes to compiler
vim src/reflaxe/elixir/ElixirCompiler.hx

# 2. Test Haxe compiler changes
npm run test:quick

# 3. Test generated Elixir code integration
npm run test:mix

# 4. Full validation
npm test

Project Structure Overview

reflaxe.elixir/
├── .haxerc                     # Haxe version specification
├── package.json                # npm dependencies and scripts  
├── mix.exs                     # Elixir dependencies and config
├── haxe_libraries/             # lix-managed Haxe dependencies
├── src/reflaxe/elixir/         # Compiler source code
├── std/                        # Phoenix/Elixir type definitions
├── test/                       # Snapshot tests for compiler
├── examples/                   # Working example applications
│   ├── todo-app/              # Main Phoenix LiveView example
│   └── simple-modules/        # Basic compilation examples
└── docs/                      # Complete documentation (you are here!)

Troubleshooting

Common Issues

Issue: haxe: command not found

Solution: Install Haxe and/or add it to your PATH.

# Preferred
haxe --version

# Project-local shim (provided by `lix` + `.haxerc`)
./node_modules/.bin/haxe --version

Issue: Unknown identifier: reflaxe

Solution: Run lix download to install dependencies

npx lix download

Issue: Tests failing on fresh install

Solution: Verify all prerequisites and run setup in order

# Complete setup sequence
npm install
npx lix download
mix deps.get
npm test

Issue: "Library reflaxe.elixir is not installed"

Solution: This is a self-referential library issue. See Troubleshooting Guide for detailed solutions.

Issue: "classpath src/ is not a directory"

Solution: Path resolution issue with test setup. This occurs when test configurations reference incorrect paths. Verify you're in the correct directory and all paths in .hxml files are accurate.

Issue: Error: ENOENT: no such file or directory, open '.haxerc'

Solution: Ensure you're in the project root directory

# Check you're in the right directory
ls .haxerc          # Should exist
pwd                 # Should end with /reflaxe.elixir

Issue: No source maps generated

Solution: Source mapping is currently experimental; .ex.map files are not emitted by default builds yet. See docs/04-api-reference/SOURCE_MAPPING.md.

Issue: Source map positions incorrect

Solution: Source mapping is currently experimental; if you’re working on it, start from docs/04-api-reference/SOURCE_MAPPING.md and add integration coverage under test/snapshot/core/source_map_validation/.

Getting Help

Check Installation Status

# Verify each component
node --version      # Node.js
npx lix --version   # lix package manager
haxe --version      # Haxe (project toolchain)
mix --version       # Elixir/Mix

Reinstall Dependencies

# Re-download the toolchain + libraries (lix cache)
npx lix download
# If your lix cache is corrupted, remove it and retry:
# rm -rf ~/haxe

# Clean reinstall Elixir dependencies  
mix deps.clean --all
mix deps.get

# Verify with tests
npm test

Project Structure Understanding

reflaxe.elixir/
├── .haxerc                     # Haxe version specification
├── package.json                # npm dependencies and scripts
├── mix.exs                     # Elixir dependencies and config
├── haxe_libraries/             # lix-managed Haxe deps (pinned via *.hxml)
├── src/reflaxe/elixir/         # Haxe→Elixir compiler source
├── std/                        # Elixir extern definitions
├── test/                       # Haxe compiler tests
├── examples/                   # Working examples
└── node_modules/               # npm dependencies (including lix)

Architecture Summary

Reflaxe.Elixir uses a dual-ecosystem architecture:

🔧 Haxe Side (npm + lix)

  • Purpose: Develop and test the compiler itself
  • Tools: lix (Haxe toolchain) + snapshot test runner under test/
  • Command: npm run test:quick

⚡ Elixir Side (mix)

  • Purpose: Test and run generated code
  • Tools: Phoenix, Ecto, ExUnit, GenServer
  • Command: npm run test:mix

🚀 Integration (npm orchestration)

  • Purpose: Validate end-to-end workflow
  • Command: npm test (runs both ecosystems)

This setup ensures that both the compiler development and generated code quality are thoroughly validated.

Next Steps

After successful installation:

  1. Quickstart Tutorial - Build your first Haxe→Elixir project in 5 minutes
  2. Project Structure - Understand the directory layout and conventions
  3. Development Workflow - Learn day-to-day development practices
  4. Phoenix Integration - Build Phoenix applications with Haxe

Additional Resources

Ready to code? Continue to Quickstart Tutorial for your first Haxe→Elixir project.