Project

shapelib

0.0
A long-lived project that still receives updates
Simple wrapper around the shapelib library
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

>= 13.0
>= 3.0
 Project Readme

Shapelib bindings for Ruby

GitHub CI builds and tests each Ruby below on Linux (Ubuntu 24.04, x86_64) and macOS (macOS 15, Apple Silicon). Badges show the latest push to main.

Ruby Linux macOS (Apple Silicon)
2.6 Ruby 2.6 / Linux Ruby 2.6 / macOS
3.3 Ruby 3.3 / Linux Ruby 3.3 / macOS
3.4 Ruby 3.4 / Linux Ruby 3.4 / macOS
4.0 Ruby 4.0 / Linux Ruby 4.0 / macOS
4.1.0-preview1 Ruby 4.1.0-preview1 / Linux Ruby 4.1.0-preview1 / macOS

This is a wrapper module of Shapefile C Library for Ruby. Originally authored by prasinos@users.sourceforge.net.

How to install

  • Install the shapelib C library with your Unix package management system.
  • It is currently tested against Ruby 2.6 through 4.1 using RVM on Ubuntu

OSX

Ruby 2.6 compatibility is currently being maintained to support the old Ruby version on MacOS.

Install MacPorts. Use it to install the shapelib C library:

sudo port install shapelib

Alternatively, use Homebrew:

brew install shapelib

Now install the Rubygem:

gem install shapelib

Troubleshooting

  • I have shapelib installed but the build fails

    Try --with-shapelib-include= and --with-shapelib-lib= options: gem install shapelib -- --with-shapelib-include=...

If above advice doesn't help, please visit http://github.com/gravatite/shapelib and post an issue.

How to use

Please see doc/Interface.html.

Date fields use YYYYMMDD Strings, or nil for nulls. With native shapelib 1.5.0 or newer, create them with ['date', :Date, 8] (or Shapelib::Date / "Date" as the type); field_type reports :Date. Writes require exactly eight ASCII digits, without calendar validation. Older native libraries continue to expose existing date fields as Strings classified as :String.

Negative measures are preserved down to and including -1e38; smaller values represent no data. New nil measures are stored as -2e38. The exact legacy marker -2e-38 remains reserved for nil, so existing gem-written nulls need no migration.

Development

Use Ruby 2.6 or newer with the development dependencies declared in shapelib.gemspec and the shapelib C library installed.

  • rake compile builds the extension locally.
  • rake test (or rake) builds the extension and runs the tests.
  • rake gem packages the sources as pkg/shapelib-<version>.gem. rake package also builds this gem.
  • rake rvm-test builds and tests every installed RVM Ruby.
  • rake c23-test builds with Clang in C23 mode and runs the tests in a fresh temporary directory. Clang is required by default; set CC or MAKE to use another compiler or make command. The build directory is printed and retained for diagnostics; the normal extension is left untouched.
  • rake rdoc builds HTML documentation when the optional rdoc gem is installed. rake rerdoc rebuilds it and rake clobber_rdoc removes it.
  • rake clean removes the current Ruby's build directory. rake clobber also removes compiled extensions, all build directories, packages, and generated documentation.
  • rake release runs the local tests, packages the gem, and pushes it to RubyGems.org using your configured credentials.

Edit metadata in shapelib.gemspec and the version in lib/shapelib/version.rb. Set MAKE to use another make command, or pass configuration options with rake compile -- --with-shapelib-include=... --with-shapelib-lib=.... These options apply when the Makefile is generated. To change them after an initial build, clean first:

rake clean compile -- --with-shapelib-include=... --with-shapelib-lib=...

License issues

Ruby-ShapeLib code and documentation are available under either MIT or LGPL version 2.0, at your option. See LICENSE, LICENSE-MIT, and LICENSE-LGPL.

The bundled Zillow neighborhood test data has a separate CC BY-SA 3.0 license. Its attribution is in LICENSE, with the full terms in LICENSE-CC-BY-SA-3.0. The native shapelib dependency retains its own license terms.