README.md

   1 MagickD
   2 =======
   3
   4 The `magickd` package provides a safe higher-level wrapper for the
   5 `GraphicsMagick` library.  For more information about `GraphicsMagick`,
   6 see the [official website].
   7
   8 [official website]: http://www.graphicsmagick.org
   9
  10
  11 Dependencies
  12 ------------
  13
  14 In order to use the `magickd` package, you must have `libGraphicsMagick`
  15 library installed where it can be found by `pkg-config`.
  16
  17 `magickd` supports D version 2.076 and higher.
  18
  19
  20 Configuration
  21 --------------
  22
  23 There are multiple ways you can configure the `magickd` package, but
  24 first, add it as a dub dependency:
  25
  26 For `dub.sdl`:
  27 ```sdl
  28 dependency "magickd" repository="git+https://repo.or.cz/magickd.git" \
  29     version="d331323932b3833aaff5cab0762c7099e3b36555"
  30 ```
  31
  32 For `dub.json`:
  33 ```json
  34 "dependencies": {
  35     "magickd": {
  36         "repository": "git+https://repo.or.cz/magickd.git",
  37         "version": "d331323932b3833aaff5cab0762c7099e3b36555"
  38     }
  39 }
  40 ```
  41
  42 With that done, you're good to go!
  43
  44 **NOTE:** ~~At some point I'll try get this package on http://dub.pm, for
  45 now though, just use the latest git hash.~~ This package won't be on The
  46 D package registry so long as they only support GitHub/GitLab/Bitbucket.
  47 In the mean time, use the latest git hash.
  48
  49 ### Dynamic bindings
  50
  51 By default, `magickd` will build a version that uses dynamic bindings.
  52 This requires loading the library at runtime and binding the symbols.
  53
  54 ```d
  55 import magickd;
  56
  57 /* Attempt to load the GraphicsMagick library. */
  58 MDLoadStatus result = loadGraphicsMagick();
  59
  60 /* Do we need to unload the library? */
  61 bool unload = false;
  62
  63 switch (result) {
  64    case MDLoadStatus.success:
  65       // All Good!
  66       unload = true;
  67       break;
  68    case MDLoadStatus.badLibrary:
  69       // We have loaded the GraphicsMagick library, but some of the symbols
  70       // that we expected to find, could not be found.
  71       // Something may not work.
  72       unload = true;
  73       break;
  74    case MDLoadStatus.noLibrary:
  75       // We couldn't find the GraphicsMagick library on the system.
  76       // Nothing will work.
  77       break;
  78    default:
  79       assert(0);
  80 }
  81
  82 if (unload) {
  83    unloadGraphicsMagick();
  84 }
  85 ```
  86
  87 **NOTE**: If you aren't using dub, make sure to specify the `GMagick_Dynamic` version when compiling.
  88
  89
  90 ### Static bindings
  91
  92 For `dub.sdl`:
  93 ```sdl
  94 dependency "magickd" repository="git+https://repo.or.cz/magickd.git" \
  95     version="d331323932b3833aaff5cab0762c7099e3b36555"
  96 versions "GMagick_Static"
  97 libs "GraphicsMagick" "GraphicsMagickWand"
  98 ```
  99
 100 For `dub.json`:
 101 ```json
 102 "dependencies": {
 103     "magickd": {
 104         "repository": "git+https://repo.or.cz/magickd.git",
 105         "version": "d331323932b3833aaff5cab0762c7099e3b36555"
 106     }
 107 },
 108 "versions": ["GMagick_Static"],
 109 "libs": ["GraphicsMagick", "GraphicsMagickWand"]
 110 ```
 111
 112 Versioning
 113 ----------
 114
 115 Each git tag will have a split in the version. The first part will be
 116 the version of MagickD; the second part will be the version of
 117 GraphicsMagick that it supports.  Primary support will be for the
 118 most recent version of GraphicsMagick, but I'm happy to support other
 119 versions if people need.
 120
 121 The general format is:
 122
 123 vX.Y.Z+A.B.C
 124
 125 X = Major version for MagickD (API breaking)
 126 Y = Minor version for MagickD (API addition)
 127 Z = Patch version (fixes that don't change API)
 128
 129 A = Major version for GraphicsMagick
 130 B = Minor version for GraphicsMagick
 131 C = Revision version for GraphicsMagick
 132
 133 License
 134 -------
 135
 136 `magickd` is licensed under the Expat license, you should have received
 137 a copy in a file named `LICENSE`.  If not, see
 138 <https://repo.or.cz/magickd.git/blob/HEAD:/LICENSE>.