Purpose

The emf2svg Ruby gem provides a Ruby interface to the libemf2svg EMF-to-SVG conversion library.

Note

This gem currently uses the claricle fork of libemf2svg where the latest portability fixes (MinGW/MSys support, arm64 CI, restored macOS x86_64 / Windows ARM64 / MSys2 workflows, etc.) live while waiting for further upstreaming. The source tarball this gem compiles from is published from claricle/libemf2svg/releases.

Prerequisites

• Ruby version >= 2.6

Install

Install the gem directly:

gem install 'emf2svg'

Or add it to your Gemfile:

gem 'emf2svg'

Note	For more information on how to install by compiling from source, see Installing from source.

Usage

This gem provides an interface to libemf2svg, allowing your Ruby code to directly utilize EMF to SVG conversion facilities.

There are two ways to provide EMF data to emf2svg.

Loading from file

Emf2svg.from_file

Loads an EMF file directly from the filesystem.

Example 1. Example of using Emf2svg.from_file and exporting an SVG file

require "emf2svg"

data = Emf2svg.from_file("example.emf", 800, 600)
File.write("output.svg", data, mode: "wb")

800, 600 - optional width and height of the bounding rectangle for svg file The image will be scaled to fit into this rectangle These parameters are optional. If skipped or set to 0 SVG image will have the same size as EMF (in pixels)

Loading binary data

Emf2svg.from_binary_string

Loads EMF content from binary form.

Example 2. Example of using Emf2svg.from_binary_string and exporting an SVG file

require "emf2svg"

emf_content = File.read("example.emf", mode: "rb")
svg_data = Emf2svg.from_binary_string(emf_content, 800, 600)
File.write("output.svg", svg_data, mode: "wb")

800, 600 - optional width and height of the bounding rectangle for svg file The image will be scaled to fit into this rectangle These parameters are optional. If skipped or set to 0 SVG image will have the same size as EMF (in pixels)

Packaging

Versioning

The gem version follows the pattern {libemf2svg_version}.{ruby_iteration}:

Segment	Meaning
libemf2svg_version	The upstream libemf2svg release this gem is built against (e.g. 1.8.2). Bumps when libemf2svg cuts a new release.
ruby_iteration	A monotonically increasing counter for Ruby-side changes that ship without a new libemf2svg release — recipe bug fixes, CI changes, documentation, gemspec tweaks. Resets to 0 whenever libemf2SVG_version bumps.

Examples:

Version	Meaning
1.8.2.0	First release built against libemf2svg 1.8.2.
1.8.2.1	Ruby-side fix on top of the same libemf2svg 1.8.2 (e.g. recipe bug).
1.8.3.0	First release built against libemf2svg 1.8.3 (iteration reset).

To find which libemf2svg version a given gem version was built against, read the first three segments. To find the Ruby-side patch level within that libemf2svg version, read the fourth.

The constants live in lib/emf2svg/version.rb:

LIBEMF2SVG_VERSION        = "1.8.2"
LIBEMF2SVG_RUBY_ITERATION = 0
VERSION                   = "#{LIBEMF2SVG_VERSION}.#{LIBEMF2SVG_RUBY_ITERATION}"

Bump LIBEMF2SVG_VERSION and reset LIBEMF2SVG_RUBY_ITERATION = 0 when pulling in a new libemf2svg release. Bump only LIBEMF2SVG_RUBY_ITERATION for Ruby-side-only changes.

Pre-compiled extensions or building from source

This gem is distributed with pre-compiled native extensions for a set of supported machine architectures.

On supported platforms, this removes the need for compiling the C extension and the installation of system dependencies. This results in much faster and a more reliable installation step.

The pre-compiled platforms are:

• x86_64-linux (GNU and musl flavors)

• aarch64-linux (GNU and musl flavors)

• x86_64-darwin

• arm64-darwin

• x64-mingw32

• x64-mingw-ucrt

When installing the gem, Ruby will automatically select a pre-compiled version suitable for your platform, or opt to install from source if the platform is not supported.

Installing from source

General

For platforms that require compilation, the emf2svg build script will automatically compile the native extension locally.

The emf2svg build script maintains and installs all required libraries and other dependencies using the vcpkg package manager.

Prior to installation, the system must already have install the appropriate build system (such as gcc, clang or Visual Studio), and CMake.

Build prerequisites by platform

Windows

On Windows, while all necessary libraries are already pre-compiled, Visual Studio 2019 with C++ Build Tools still need to be installed.

They can be downloaded here, or installed with Chocolatey:

choco install visualstudio2019buildtools -y --no-progress --package-parameters "--add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows10SDK.18362"

macOS

On macOS, CMake needs to be installed.

brew install cmake

Linux: Debian

On Debian, the following build tools need to be installed.

# Choose your preferred compiler
# GCC
apt-get install gcc g++ gperf cmake pkg-config
# or
# clang
apt-get install clang gperf cmake pkg-config

Note	On Debian systems, there exists a vcpkg bug that needs to be addressed by installing the gperf package in addition to other build tools.

Linux: Fedora

On Fedora, the following build tools need to be installed.

yum install cmake gcc-c++ gcc

Development

Basic steps

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Releasing

Releases are cut from the release.yml workflow. It has two triggers:

workflow_dispatch (preferred)

Manually triggered from the Actions UI with a bump-type input that decides how lib/emf2svg/version.rb is rewritten before tagging:

bump-type	Effect
current	Tag and publish the VERSION currently in version.rb (no edit, no commit). Use this for the first release of a new LIBEMF2SVG_VERSION.
iteration	Bump LIBEMF2SVG_RUBY_ITERATION by 1, commit, tag, publish. Use this for Ruby-side-only fixes (recipe, CI, docs).
libemf2svg	Set LIBEMF2SVG_VERSION to the supplied libemf2svg-version (e.g. 1.8.3), reset LIBEMF2SVG_RUBY_ITERATION to 0, commit, tag, publish.

The workflow pushes the bump commit (if any) to master, pushes the vX.Y.Z.N tag, then builds pre-compiled native gems for every supported platform and publishes them to rubygems.org using RubyGems Trusted Publishing (OIDC).

push: tags: v*

If a human pushes a tag manually (e.g. for an emergency re-release after editing version.rb locally), the same build + publish pipeline runs without the bump step.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/claricle/emf2svg-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Code of Conduct

Everyone interacting in the emf2svg project’s codebases, issue trackers, chat rooms, mailing lists is expected to follow the code of conduct.