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 | ||
| 3.3 | ||
| 3.4 | ||
| 4.0 | ||
| 4.1.0-preview1 |
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 compilebuilds the extension locally. -
rake test(orrake) builds the extension and runs the tests. -
rake gempackages the sources aspkg/shapelib-<version>.gem.rake packagealso builds this gem. -
rake rvm-testbuilds and tests every installed RVM Ruby. -
rake c23-testbuilds with Clang in C23 mode and runs the tests in a fresh temporary directory. Clang is required by default; setCCorMAKEto use another compiler or make command. The build directory is printed and retained for diagnostics; the normal extension is left untouched. -
rake rdocbuilds HTML documentation when the optionalrdocgem is installed.rake rerdocrebuilds it andrake clobber_rdocremoves it. -
rake cleanremoves the current Ruby's build directory.rake clobberalso removes compiled extensions, all build directories, packages, and generated documentation. -
rake releaseruns 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.