Merge pull request #51 from tomassedovic/build-script

Convert to the supported Cargo build script

This should make it more consistent to build & use the native libtcod bindings for everyone. We've moved from the old anything-goes build scripts to the new ones that only allow Rust code.

Based on the conventions in the build-script guide[1], this introduces a new crate called `tcod-sys`. That crate defines all the function signatures and type definitions in `libtcod` and so replaces what was previously in `tcod-rs/src/ffi.rs`. It also bundles a libtcod snapshot source known to work (the latest checkout of the `1.5.x` branch) plus fixes to make it compile on Mac OS X. And a build script that knows how to build it and where to put the artifacts.

This should hopefully make building tcod-rs more repeatable for everyone.

This is a breaking change.

To migrate, just make sure you have the right dependencies to build libtcod installed (see readme) and remove any `build = ...` section from your game's `Cargo.toml`. When you run `cargo build`, libtcod will be built as part that build process.

If you want to avoid building libtcod and provide your own pre-built `libtcod.{so,dll,dylib}`, you can use Cargo's build override mechanism[2]. See `tcod-rs/.cargo/config` for an example. You probably want to put the `.cargo/config` file in the root of your game, but it can be in any directory above that, too (such as your `$HOME`).

I have tested this on my 64bit Linux Mint 17 machine and a 32bit Windows 7 box with MinGW. @pmsanford tested this on OSX.

[1]: http://doc.crates.io/build-script.html
[2]: http://doc.crates.io/build-script.html#overriding-build-scripts

Closes #32.

Author: tomassedovic

.cargo/config

@@ -0,0 +1,39 @@
+# Using binary distribution of libtcod instead of building it from source:
+# For more info, read: http://doc.crates.io/build-script.html and http://doc.crates.io/config.html
+#
+# In general, you download your the compiled libraries (libtcod.so/dll/ and
+# libtcodgui.so/dll), put them into `precompiled/$target` and uncomment the
+# corresponding section below.
+
+
+# 64-bit Linux:
+#
+# Download this: http://roguecentral.org/doryen/?file_id=28
+# Copy libtcod.so and libtcodgui.so to: precompiled/x86_64-unknown-linux-gnu
+# You may also need to create libtcod.so.1 and libtcodgui.so.1 because reasons?
+# Uncomment this section:
+#
+# [target.x86_64-unknown-linux-gnu.tcod]
+# rustc-flags = "-L precompiled/x86_64-unknown-linux-gnu -l tcod"
+
+
+# 32-bit Linux:
+#
+# Download this: http://roguecentral.org/doryen/?file_id=26
+# Copy libtcod.so and libtcodgui.so to: precompiled/i686-unknown-linux-gnu
+# You may also need to create libtcod.so.1 and libtcodgui.so.1 because reasons?
+# Uncomment this section:
+#
+# [target.i686-unknown-linux-gnu.tcod]
+# rustc-flags = "-L precompiled/i686-unknown-linux-gnu -l tcod"
+
+
+# Windows:
+#
+# Download this: http://roguecentral.org/doryen/?file_id=27
+# Copy libtcod-mingw.dll, libtcod-gui-mingw.dll and SDL.dll to: precompiled/i686-pc-windows-gnu
+# You must also create libtcod.dll and libtcod-gui.dll because reasons?
+# Uncomment this section:
+#
+# [target.i686-pc-windows-gnu.tcod]
+# rustc-flags = "-L precompiled/i686-pc-windows-gnu -l tcod"

.gitignore

@@ -1,10 +1,11 @@
 .DS_Store
 *~
 *#
+*.a
 *.o
 *.so
-*.swp
 *.dylib
+*.swp
 *.dSYM
 *.dll
 *.rlib
@@ -24,3 +25,6 @@ watch.sh
 !/examples/*.rs
 !/examples/assets/
 /Cargo.lock
+/tcod-sys/target/
+!/tcod-sys/libtcod/SDL*.dll
+!/tcod-sys/libtcod/dependencies/**

.travis.yml

@@ -2,10 +2,7 @@ language: rust
 before_install:
   - sudo apt-get update -qq
 install:
-  - sudo apt-get install -y libsdl1.2debian
-  - curl -L "http://roguecentral.org/doryen/?file_id=28" -o libtcod-1.5.1-linux64.tar.gz
-  - tar -xzf libtcod-1.5.1-linux64.tar.gz
-  - sudo cp libtcod-1.5.1/libtcod{,gui}.so /usr/lib/x86_64-linux-gnu/
+  - sudo apt-get install -y upx electric-fence libsdl1.2-dev
 script:
   - cargo build --verbose
   - cargo test --verbose

Cargo.toml

@@ -2,13 +2,13 @@
 name = "tcod"
 version = "0.3.0"
 authors = ["[email protected]", "[email protected]"]
-build = "./build.sh"
 
 [lib]
-
 name = "tcod"
 path = "src/lib.rs"
 
+[dependencies.tcod-sys]
+path = "tcod-sys"
 
 # TODO: temporarily disabling debuginfo until this is fixed:
 # https://github.com/rust-lang/rust/issues/17257

README.md

@@ -1,17 +1,17 @@
 libtcod bindings for Rust
 -------------------------
 
-[libtcod a.k.a. "The Doryen Library"](http://doryen.eptalys.net/libtcod/) is a
-smallish library designed for writing roguelikes. It provides a bunch of useful
-functionality such as:
+[libtcod a.k.a. "The Doryen Library"](http://roguecentral.org/doryen/libtcod/)
+is a smallish library designed for writing roguelikes. It provides a bunch of
+useful functionality such as:
 
 * Text-based graphics API that doesn't suck as much as curses or OpenGL
 * Colours! (like, more than 16)
 * Keyboard and mouse input
 * Path finding
 * Field of view
 * Portable (works on linux and windows; mac too but requires some effort)
-* [lots of other stuff](http://doryen.eptalys.net/libtcod/features/)
+* [lots of other stuff](http://roguecentral.org/doryen/libtcod/features/)
 
 
 This project provides [Rust](http://www.rust-lang.org/) bindings for libtcod
@@ -49,7 +49,7 @@ complete however.
 * Most of the _Console_ features (new, init_root, blit, putting text on the
   screen, reading key presses, etc.)
 * Most of _Map_ (new, size, set, is_walkable)
-* Most of the A* _Path_ features (no Dijkstra yet)
+* A* and Dijkstra _Path_ finding
 * Some of the _System_ layer (get/set FPS, last frame length)
 
 ### Probably Won't Ever Be Implemented Because Rust Provides This Already
@@ -66,88 +66,91 @@ complete however.
 How to use this
 ---------------
 
-You can build this library by cloning the repository and typing `cargo build`. You need to have `libtcod` in your library path, you can
-download it from the [libtcod download page](http://doryen.eptalys.net/libtcod/download/), or install it using some package manager. See below for Mac OS X specific install instructions.
+`tcod-rs` depends on `libtcod` so you need to build or download the official
+version. The `libtcod` version known to work is bundled with `tcod-sys` and
+Cargo will build it for you, but you need the build dependencies installed.
 
-This will compile and link the library and a simple example in `target`
+Alternatively, you can provide the precompiled libtcod library to override the
+building process. [See below](#using-existing-binary-distribution).
 
-Other than that, look at the source and read
-[libtcod documentation](http://doryen.eptalys.net/data/libtcod/doc/1.5.1/index2.html?c=true&cpp=true&cs=true&py=true&lua=true).
+To use `tcod-rs`, add this to your game's `Cargo.toml`:
 
-## OS X specific instructions
+    [dependencies.tcod]
+    git = "https://github.com/tomassedovic/tcod-rs.git"
 
-There are two dependencies to installing on OS X:
- * [Homebrew](http://brew.sh/)
- * `mercurial`
- * `sdl`
- * `wget`
- * `libtcod`
 
-Unfortunately, `libtcod` is no longer officially supported on Mac OS X. As of 8/20/2014 the following instructinos work:
+### Building on Linux
 
-Start off by installing `mercurial`, `sdl` and `wget`:
+Run the equivalent of:
 
-```sh
-brew install mercurial sdl wget
-```
+    $ sudo apt-get install gcc g++ make upx electric-fence libsdl1.2-dev mercurial
+    $ cd yourgame
+    $ cargo build
+    $ cargo run
 
-Then clone the offical `libtcod` repository (it helps if you put it in a safe place, like `~/src` or something):
+on your distro.
 
-```sh
-hg clone https://bitbucket.org/jice/libtcod
-```
+You can also check the [official libtcod build instructions for Linux][linux].
 
-Make sure you use the supported libtcod version:
+linux: http://roguecentral.org/doryen/data/libtcod/doc/1.5.2/html2/compile_libtcod_linux.html?c=true
 
-```sh
-cd libtcod
-hg checkout 1.5.x
-```
 
-Then make `libtcod` with the following commands:
+### Building on Windows (with MinGW)
 
- ```sh
-wget https://gist.githubusercontent.com/jaredonline/daf3c5f1ea6c7ca00e29/raw/ae91b3e47bf0de5b772eff882e477d8144cfbaf8/makefile-osx > makefiles/makefile-osx
-wget https://dl.dropboxusercontent.com/u/169446/osx.tar.gz
-tar -xzvf osx.tar.gz
-make -f makefiles/makefile-osx
-```
+The Windows version of `libtcod` relies on MinGW and MSYS so you have to install
+them:
 
-If this seems a bit convoluted that's because it is. I managed to find instructions [here](http://zackhovatter.com/gamedev/2013/11/26/building-libtcod-on-os-x-mavericks.html) but at the time of writing that link was broken. I grabbed a screenshot from Google Cache and put together my own packages of OS X specific materials. In step two above you're getting an OS X specific makefile and in step three you're getting some OS X specific headers.
+1. [Download and run MinGW][mingw]
+2. In the MinGW installer, mark the following sections for installation:
+   * C compiler (gcc)
+   * C++ compiler (g++)
+   * MSYS Basic System
+3. Open the Command prompt (cmd.exe)
+4. Run:
 
-You can test that it all worked by running
+    cd yourgame
+    cargo build
+    cargo run
 
-```sh
-./samples_c
-./samples_cpp
-```
+mingw: http://sourceforge.net/projects/mingw/files/
 
-And you should get some pretty windows.
+You can also check the [official libtcod build instructions for Windows][windows].
 
-### Building a project with it:
+windows: http://roguecentral.org/doryen/data/libtcod/doc/1.5.2/html2/compile_libtcod_mingw.html?c=true
 
-Now, to get a project up and running with Cargo, add this to your `Cargo.toml` file:
 
-```toml
-build = "sh .build.sh"
+### Building on Mac OS X
 
-[dependencies.tcod]
-git = "https://github.com/tomassedovic/tcod-rs.git"
-```
+1. [Install Homebrew](http://brew.sh/)
+2. Run:
 
-And add this file to your project root (`.build.sh`):
+    $ brew install sdl wget
+    $ cd yourgame
+    $ cargo build
+    $ cargo run
 
-```sh
-#!/bin/sh
+This is based on the instructions from [Jared McFarland's roguelike tutorial][macosx].
 
-export LIBTCOD_SRC_DIR="/PATH/TO/YOUR/src/libtcod"
-cp $LIBTCOD_SRC_DIR/*.dylib $OUT_DIR/
-cp $LIBTCOD_SRC_DIR/terminal.png $OUT_DIR/../../../
-```
+macosx: http://jaredonline.svbtle.com/roguelike-tutorial-in-rust-part-1
 
-That copies the required `.dyblib` files from where you built `libtcod` to your project's target directory, and the `terminal.png` that `sdl` requires to your projects root directory.
+---
+
+To test this, you can clone this repository directly and run the one of the
+provided examples:
+
+    $ git clone https://github.com/tomassedovic/tcod-rs.git
+    $ cd tcod-rs
+    $ cargo run --example keyboard
+
+
+### Using existing binary distribution
+
+If you don't want to build libtcod yourself, you can
+[instruct Cargo to override the build script][override]. See `.cargo/config`
+from the repository for an example.
+
+override: http://doc.crates.io/build-script.html#overriding-build-scripts
 
-After that you should be good to go! Happy building!
 
 Contributing
 ------------
@@ -173,9 +176,14 @@ You can regenerate the raw bindings by running:
 
 ### Contributors
 
-* Edu Garcia <[email protected]>
-* Jared McFarland <[email protected]>
-* Tomas Sedovic <[email protected]>
+
+* Bastien Léonard, @bastienleonard, <[email protected]>
+* Edu Garcia, @Arcnor, <[email protected]>
+* @Moredread
+* Jared McFarland, @jaredonline, <[email protected]>
+* Paul Sanford, @pmsanford, <[email protected]>
+* @Pranz, <[email protected]>
+* Tomas Sedovic, @tomassedovic, <[email protected]>
 
 
 ### License

build.sh

@@ -13,7 +13,7 @@ fn main() {
     // Uses the default foreground and background:
     con.put_char(40, 25, '@', BackgroundFlag::Set);
     // Custom foreground and background:
-    con.put_char_ex(42, 25, '!', Color::new(240, 13, 20), Color::new(0, 0, 0));
+    con.put_char_ex(42, 25, '!', Color{r: 240, g: 13, b: 20}, Color{r: 0, g: 0, b: 0});
 
     Console::flush();