Installation

Purpose

This guide covers how to install Moxml and set up your chosen XML adapter for Ruby applications.

Requirements

  • Ruby >= 3.0.0

  • At least one supported XML library (Nokogiri, LibXML, Oga, REXML, or Ox)

Basic installation

Add Moxml and your chosen XML adapter to your Gemfile:

# Gemfile
gem 'moxml'

# Choose one or more XML adapters:
gem 'nokogiri'      # Recommended: Fast, widely used
gem 'libxml-ruby'   # Alternative: Native performance
gem 'oga'           # Pure Ruby: No C extensions
gem 'ox'            # Fastest: Best for simple documents
# REXML is included in Ruby standard library

Then install:

bundle install

Installing without Bundler

Install directly using gem:

gem install moxml
gem install nokogiri  # Or your preferred adapter

Adapter selection

Moxml automatically detects and uses available XML libraries. The default adapter priority order is:

  1. Nokogiri (if available)

  2. LibXML (if available)

  3. Oga (if available)

  4. REXML (always available)

  5. Ox (if available)

You can override the default adapter in your application:

# Set default adapter globally
Moxml::Config.default_adapter = :libxml

# Or configure per instance
moxml = Moxml.new
moxml.config.adapter = :oga

Verifying installation

Test your installation:

require 'moxml'

# Check version
puts Moxml::VERSION

# Verify adapter loaded
context = Moxml.new
puts context.config.adapter.name
# => "Moxml::Adapter::Nokogiri" (or your adapter)

# Parse simple XML
doc = context.parse('<root><child>test</child></root>')
puts doc.root.name
# => "root"

Troubleshooting

Gem not found:

Ensure bundler is using the correct gem source:

# Add to top of Gemfile
source 'https://rubygems.org'

Adapter not loading:

If your chosen adapter isn’t loading:

  1. Verify the adapter gem is installed: bundle list | grep nokogiri

  2. Check for version conflicts: bundle update moxml

  3. Try explicitly requiring: require 'nokogiri' before require 'moxml'

C extension compilation errors:

If Nokogiri or LibXML fail to install on your system, consider using pure Ruby adapters:

gem 'moxml'
gem 'oga'  # Pure Ruby alternative

Or use REXML which requires no additional gems:

gem 'moxml'
# REXML is included in Ruby standard library

Next steps