doc: add install guide and an example

CHANGELOG.md

@@ -5,6 +5,27 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 This file follows the convention described at
 [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 
+## [1.0.0] - 2024-05-25
+### Added
+- An example! After 9 years, finally an example.
+### Changed
+- **BREAKING CHANGES**
+    * 5ohue: Refactored the current `CompositeOperator` and `ResourceType` types
+      into a separate module and added many new enum wrappers around ImageMagick
+      types. the caller will have less need to directly touch the `bindings`
+      module to pass arguments to functions. For instance, the
+      `bindings::FilterType_GaussianFilter` type is now replaced with
+      `FilterType::Gaussian`, lending the API a more Rust-like aesthetic.
+    * 5ohue: Replaced the not so helpful `MagickError("failed to resize image")`
+      with `MagickError(self.get_exception()?.0)`. This should provide more
+      helpful error messages. In some cases there is no exception given when a
+      failure occurs and the caller will only see `Error:` which is even less
+      helpful than before. This is due to the way the MagickWand API works,
+      unfortunately.
+    * 5ohue: Add `impl Send` for wand types.
+- This crate will now adhere to the semantic versioning practice more rigidly
+  than it had been while evolving in a pre-1.0 state.
+
 ## [0.21.0] - 2024-04-17
 ### Added
 - yoghurt-x86: added `MagickNormalizeImage()` and `MagickOrderedDitherImage()`

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "magick_rust"
-version = "0.21.0"
+version = "1.0.0"
 authors = ["Nathan Fiedler <nathanfiedler@fastmail.fm>"]
 description = "Selection of Rust bindings for the ImageMagick library."
 homepage = "https://github.com/nlfiedler/magick-rust"
@@ -9,6 +9,10 @@ readme = "README.md"
 license = "Apache-2.0"
 keywords = ["magickwand", "imagemagick"]
 build = "build.rs"
+exclude = [
+    "docker/*",
+    "test/*",
+]
 
 [dependencies]
 libc = "0.2"

INSTALL.md

@@ -0,0 +1,115 @@
+# Installation
+
+The `README.md` covers the basic requirements for building and using this crate. In theory, if you have all of the requisite image libraries, ImageMagick, and Rust installed, then simply adding this crate as a dependency should be enough. If that did not work as expected, then keep reading.
+
+## In an ideal world
+
+If everything is set up just right, then add the crate and proceed as usual.
+
+```
+cargo add magick_rust
+cargo build
+```
+
+But we don't live in an ideal world, so keep reading.
+
+## ImageMagick
+
+Many Linux distributions will have the older **6.x** versions of the ImageMagick library. With the release of **7.0**, ImageMagick introduced some breaking API changes, and that may be why the Linux distros are still using the older versions. This crate only knows how to work with the **7.x** versions of ImageMagick, which means we will be building ImageMagick from source in the examples below.
+
+## Image Libraries
+
+If you build ImageMagick and at some point try to use `magick_rust` only to get the dreaded `failed to read file` error, this is because typical ImageMagick functions return 1 (good) or 0 (bad), which offers no help at all in debugging problems like this. When this error occurs, it almost certainly means that you are missing an image library that ImageMagick relies upon to process the image in question. See the detailed steps below for some examples of installing the popular image libraries, JPEG and PNG.
+
+## Installing on Linux
+
+Install build tools, Clang, some popular image libraries, and ImageMagick. Note that on most Linux distributions the package for ImageMagick is the older **6.x** which is too old for this crate.
+
+```shell
+sudo apt-get install build-essential clang pkg-config libjpeg-dev libpng-dev
+wget https://imagemagick.org/archive/ImageMagick.tar.gz
+tar axf ImageMagick.tar.gz
+cd ImageMagick-*
+./configure --with-magick-plus-plus=no --with-perl=no
+make
+sudo make install
+cd ..
+```
+
+Install Rust, if it is not already installed:
+
+```shell
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+. "$HOME/.cargo/env"
+```
+
+Create the example and copy the code that follows into the `src/main.rs` file.
+
+```shell
+cargo new --bin mrexample
+cd mrexample
+cargo add magick_rust
+```
+
+You probably do not have a `snow-covered-cat.jpg` so feel free to find a file with that name or change the name to an image file of your choosing. This code is from the `examples/thumbnail-cat.rs` example with some minor changes.
+
+```rust
+use magick_rust::{magick_wand_genesis, MagickError, MagickWand};
+use std::fs;
+use std::sync::Once;
+
+static START: Once = Once::new();
+
+fn resize(filepath: &str) -> Result<Vec<u8>, MagickError> {
+    START.call_once(|| {
+        magick_wand_genesis();
+    });
+    let wand = MagickWand::new();
+    wand.read_image(filepath)?;
+    wand.fit(240, 240);
+    wand.write_image_blob("jpeg")
+}
+
+fn main() {
+    match resize("snow-covered-cat.jpg") {
+        Ok(bytes) => {
+            fs::write("thumbnail-cat.jpg", bytes).expect("write failed");
+        }
+        Err(err) => println!("error: {}", err),
+    }
+}
+```
+
+Now we can finally build the example and test it out. Note that an alternative to setting `LD_LIBRARY_PATH` over and over again is to create a file in `/etc/ld.so.conf.d` that has the path `/usr/local/lib` in it.
+
+```shell
+export LD_LIBRARY_PATH=/usr/local/lib
+cargo build
+cargo run
+```
+
+Hopefully that produced a `thumbnail-cat.jpg` file.
+
+### Debugging
+
+Maybe that failed with the "failed to read file" error, in which case you can double-check that the image libraries were found and linked into the final binary. Use the `ldd` tool as shown below to make sure there are no libraries that were "not found". If there are any, make sure to install the requisite library, and then try `ldd` again.
+
+```shell
+$ ldd target/debug/mrexample
+	linux-vdso.so.1 (0x00007ffee63bd000)
+	libMagickWand-7.Q16HDRI.so.10 => /usr/local/lib/libMagickWand-7.Q16HDRI.so.10 (0x00007fd348e52000)
+	libMagickCore-7.Q16HDRI.so.10 => /usr/local/lib/libMagickCore-7.Q16HDRI.so.10 (0x00007fd348a54000)
+	libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fd348a2d000)
+	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fd348804000)
+	/lib64/ld-linux-x86-64.so.2 (0x00007fd348fc8000)
+	libgomp.so.1 => /lib/x86_64-linux-gnu/libgomp.so.1 (0x00007fd3487ba000)
+	libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fd3486d1000)
+	libjpeg.so.8 => /lib/x86_64-linux-gnu/libjpeg.so.8 (0x00007fd348650000)
+	libpng16.so.16 => /lib/x86_64-linux-gnu/libpng16.so.16 (0x00007fd348615000)
+	libxml2.so.2 => /lib/x86_64-linux-gnu/libxml2.so.2 (0x00007fd348433000)
+	libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 (0x00007fd348417000)
+	libicuuc.so.70 => /lib/x86_64-linux-gnu/libicuuc.so.70 (0x00007fd34821a000)
+	liblzma.so.5 => /lib/x86_64-linux-gnu/liblzma.so.5 (0x00007fd3481ef000)
+	libicudata.so.70 => /lib/x86_64-linux-gnu/libicudata.so.70 (0x00007fd3465d1000)
+	libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007fd3463a5000)
+```

README.md

@@ -1,21 +1,22 @@
 # magick-rust
 
-A somewhat safe Rust interface to the [ImageMagick](http://www.imagemagick.org/) system, in particular, the MagickWand library. Many of the functions in the MagickWand API are still missing, but over time more will be added. Pull requests are welcome.
+A somewhat safe Rust interface to the [ImageMagick](http://www.imagemagick.org/) system, in particular, the MagickWand library. Many of the functions in the MagickWand API are still missing, but over time more will be added. Pull requests are welcome, as are bug reports, and requests for examples.
 
 ## Dependencies
 
-* Rust stable
-* ImageMagick (version 7.0.10-36 to 7.1.x)
-    - Does _not_ work with ImageMagick 6.x due to backward incompatible changes.
+* [Rust](https://www.rust-lang.org) stable
+* [ImageMagick](https://imagemagick.org) (version 7.0.10-36 to 7.1.x)
+    - Does _not_ work with ImageMagick **6.x** due to backward incompatible changes.
     - [FreeBSD](https://www.freebsd.org): `sudo pkg install ImageMagick7`
     - [Homebrew](http://brew.sh): `brew install imagemagick`
-    - Linux may require building ImageMagick from source, see the `docker/Dockerfile` for an example
+    - Linux may require building ImageMagick from source, see the [INSTALL.md](./INSTALL.md) guide
     - Windows: download `*-dll` [installer](https://www.imagemagick.org/script/download.php#windows). When installing, check the *Install development headers and libraries for C and C++* checkbox.
-* [Clang](https://clang.llvm.org) (version 3.5 or higher)
-    - Or whatever version is dictated by [rust-bindgen](https://github.com/rust-lang/rust-bindgen)
+* [Clang](https://clang.llvm.org) (version 5.0 or higher, as dictated by [rust-bindgen](https://github.com/rust-lang/rust-bindgen))
 * Windows requires MSVC toolchain
-    - Download the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) and select the `MSVC ... build tools` (latest version with appropriate architecture) and `Windows 10 SDK` (or 11 if using Windows 11) at a minimum.
-* Optionally `pkg-config`, to facilitate linking with ImageMagick. Or you can set linker parameters via environment variables as described in the next section.
+    - Download the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) and select the `MSVC ... build tools` (latest version with appropriate architecture) and `Windows 11 SDK` (or `10` if using Windows 10).
+* Optionally `pkg-config`, to facilitate linking with ImageMagick. Alternatively, you can set linker parameters via environment variables as described in the next section.
+
+For detailed examples, see the [INSTALL.md](./INSTALL.md) guide, along with some discussion about the various dependencies.
 
 ## Build and Test
 
@@ -47,34 +48,9 @@ When building on Windows, you will need to set the `IMAGE_MAGICK_DIR` environmen
 
 The API documentation is available at [github pages](https://nlfiedler.github.io/magick-rust) since the docs.rs system has a hard time building anything that requires an external library that is not wrapped in a "sys" style library. See [issue 57](https://github.com/nlfiedler/magick-rust/issues/57) for the "create a sys crate request."
 
-## Example Usage
+## Examples
 
-MagickWand has some global state that needs to be initialized prior to using the library, but fortunately Rust makes handling this pretty easy. In the example below, we read in an image from a file and resize it to fit a square of 240 by 240 pixels, then convert the image to JPEG.
-
-```rust
-use magick_rust::{MagickWand, magick_wand_genesis};
-use std::sync::Once;
-
-// Used to make sure MagickWand is initialized exactly once. Note that we
-// do not bother shutting down, we simply exit when we're done.
-static START: Once = Once::new();
-
-fn resize() -> Result<Vec<u8>, &'static str> {
-    START.call_once(|| {
-        magick_wand_genesis();
-    });
-    let wand = MagickWand::new();
-    try!(wand.read_image("kittens.jpg"));
-    wand.fit(240, 240);
-    wand.write_image_blob("jpeg")
-}
-```
-
-Writing the image to a file rather than an in-memory blob is done by replacing the call to `write_image_blob()` with `write_image()`, which takes a string for the path to the file.
-
-## Frequent API Changes
-
-Because rust-bindgen changes from time to time, and is very difficult to use for a library as large as ImageMagick, the API of this crate may experience dramatic mood swings. Typically this pain manifests itself in the way the enums are represented. I am deeply sorry for this pain. Hopefully someone smarter than me can fix it some day. Pull requests are welcome.
+MagickWand has some global state that needs to be initialized prior to using the library, but fortunately Rust makes handling this pretty easy by use of the `std::sync::Once` type. See the example code in the `examples` directory for the basic usage of the crate.
 
 ## Contributing
 

examples/thumbnail-cat.rs

@@ -0,0 +1,32 @@
+//
+// Copyright (c) 2024 Nathan Fiedler
+//
+extern crate magick_rust;
+use magick_rust::{magick_wand_genesis, MagickError, MagickWand};
+use std::fs;
+use std::sync::Once;
+
+// Used to make sure MagickWand is initialized exactly once. Note that we do not
+// bother shutting down, we simply exit when we're done.
+static START: Once = Once::new();
+
+// Read the named file and create a thumbnail bound by a rectangle that is 240
+// by 240 pixels (for snow-covered-cat.jpg it will be 240x191 pixels).
+fn resize(filepath: &str) -> Result<Vec<u8>, MagickError> {
+    START.call_once(|| {
+        magick_wand_genesis();
+    });
+    let wand = MagickWand::new();
+    wand.read_image(filepath)?;
+    wand.fit(240, 240);
+    wand.write_image_blob("jpeg")
+}
+
+fn main() {
+    match resize("tests/data/snow-covered-cat.jpg") {
+        Ok(bytes) => {
+            fs::write("thumbnail-cat.jpg", bytes).expect("write failed");
+        }
+        Err(err) => println!("error: {}", err),
+    }
+}