Merge pull request #41 from smoked-herring/feature/vcpkg

Feature/vcpkg [closes #39]

BUILDING.md

@@ -0,0 +1,115 @@
+## Building SAIL
+
+Consider [EXAMPLES](EXAMPLES.md) after building and installing.
+
+### CMake options overview
+
+- `SAIL_BUILD_EXAMPLES=ON|OFF` - Build examples. Default: `ON`
+- `SAIL_BUILD_TESTS=ON|OFF` - Build tests. Default: `ON`
+- `SAIL_COLORED_OUTPUT=ON|OFF` - Enable colored console output on Windows >= 10 and Unix platforms. Default: `ON`
+- `SAIL_DEV=ON|OFF` - Enable developer mode with pedantic warnings and possible `ASAN` enabled for examples. Default: `OFF`
+- `SAIL_EXCEPT_CODECS="a;b;c"` - Enable all codecs except the codecs specified in this ';'-separated list.
+  Codecs with missing dependencies will be disabled regardless this setting. Default: empty list
+- `SAIL_ONLY_CODECS="a;b;c"` - Enable only the codecs specified in this ';'-separated list.
+  Codecs with missing dependencies will be disabled regardless this setting. Default: empty list
+- `SAIL_READ_OUTPUT_BPP32_BGRA=ON|OFF` - Make the read operations output BPP32-BGRA pixels instead of BPP32-RGBA. Default: `OFF`
+- `SAIL_VCPKG=ON|OFF` - Enable VCPKG dependency manager instead of pkg-config on Windows. See the option documentation for more. Default: `OFF`
+
+### Windows (VCPKG)
+
+SAIL is available in VCPKG:
+
+```
+vcpkg install sail
+```
+
+### Windows (standalone bundle)
+
+#### Tested environments
+
+- Windows 7 x64
+
+#### Build requirements
+
+- git
+- cmake 3.10 or later
+- MSVC 2019 or later
+
+#### Build steps
+
+Open `Git Bash` (installed along with `git`) and execute the following commands:
+
+```
+git clone --recursive https://github.com/smoked-herring/sail.git
+cd sail
+
+# Compile third-party dependencies
+cd extra
+./build
+cd ..
+
+# Compile SAIL
+mkdir build
+cd build
+cmake -A x64 -DCMAKE_INSTALL_PREFIX="C:\SAIL" ..
+cmake --build . --config Release
+
+# Install
+cmake --build . --config Release --target install
+```
+
+### macOS
+
+#### Tested environments
+
+- macOS 10.14 Mojave
+- macOS 10.15 Catalina
+
+#### Installation steps
+
+```
+brew install smoked-herring/sail/sail
+```
+
+Or
+
+```
+brew upgrade sail
+```
+
+### Linux
+
+#### Tested environments
+
+- LUbuntu 18.04 64-bit
+
+#### Build requirements
+
+- git
+- cmake 3.6 or later
+- pkg-config
+- GCC and G++ 7.5 or later
+- standard C/C++ development files installed (usually installed by metapackages like `build-essential`)
+- codec-specific development libraries installed. You can grab the list from `debian/control`
+
+#### Build steps
+
+```
+git clone --recursive https://github.com/smoked-herring/sail.git
+cd sail
+
+# Install the required dependencies grabbed from debian/control
+sudo apt install ...
+
+# Compile SAIL
+mkdir build
+cd build
+cmake ..
+make
+
+# Install
+... distro-specific installation
+```
+
+Debian rules are provided as well.
+

CMakeLists.txt

@@ -16,13 +16,13 @@ include(CMakePushCheckState)
 # Our own cmake scripts
 #
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" "${CMAKE_MODULE_PATH}")
+include(sail_check_include)
 include(sail_codec)
 include(sail_enable_asan)
 include(sail_enable_pch)
 include(sail_enable_posix_source)
 include(sail_install_cmake_config)
 include(sail_test)
-include(sail_check_build_essential)
 
 # Sanity checks
 #
@@ -46,14 +46,14 @@ sail_check_include(stdint.h)
 sail_check_include(stdio.h)
 sail_check_include(stdlib.h)
 sail_check_include(string.h)
+sail_check_include(sys/stat.h)
+sail_check_include(sys/types.h)
 sail_check_include(wchar.h)
 
 if (UNIX)
     sail_check_include(dirent.h)
     sail_check_include(dlfcn.h)
-    sail_check_include(sys/stat.h)
     sail_check_include(sys/time.h)
-    sail_check_include(sys/types.h)
     sail_check_include(unistd.h)
 endif()
 
@@ -66,12 +66,24 @@ endif()
 
 # Options
 #
+option(SAIL_BUILD_EXAMPLES "Build examples." ON)
+option(SAIL_BUILD_TESTS "Build tests." ON)
 option(SAIL_DEV "Enable developer mode. Be more strict when compiling source code, for example." OFF)
-set(SAIL_ONLY_CODECS "" CACHE STRING "Enable only the codecs specified in this ';'-separated list. \
-Codecs with missing dependencies will be disabled regardless this setting")
 set(SAIL_EXCEPT_CODECS "" CACHE STRING "Enable all codecs except the codecs specified in this ';'-separated list. \
 Codecs with missing dependencies will be disabled regardless this setting")
+set(SAIL_ONLY_CODECS "" CACHE STRING "Enable only the codecs specified in this ';'-separated list. \
+Codecs with missing dependencies will be disabled regardless this setting")
 option(SAIL_READ_OUTPUT_BPP32_BGRA "Make the read operations output BPP32-BGRA pixels instead of BPP32-RGBA." OFF)
+option(SAIL_VCPKG_PORT "Build as a VCPKG port. Intended to be used only by VCPKG. When enabled, sets SAIL_VCPKG to ON" OFF)
+option(SAIL_VCPKG "Enable VCPKG dependency manager instead of pkg-config on Windows. When enabled, please specify CMAKE_TOOLCHAIN_FILE and CMAKE_BUILD_TYPE. See the vcpkg tutorial for more." OFF)
+
+if (SAIL_VCPKG_PORT)
+    set(SAIL_VCPKG ON)
+endif()
+
+if (SAIL_VCPKG AND NOT WIN32)
+    message(FATAL_ERROR "VCPKG support is Windows-only")
+endif()
 
 if (SAIL_READ_OUTPUT_BPP32_BGRA)
     set(SAIL_DEFAULT_READ_OUTPUT_PIXEL_FORMAT "BPP32-BGRA")
@@ -163,35 +175,37 @@ if (APPLE)
     set(SAIL_APPLE ON)
 endif()
 
-# Common required packages
+# pkg-config setup
 #
-if (WIN32)
-    set(PKG_CONFIG_EXECUTABLE "${PROJECT_SOURCE_DIR}/extra/bin/pkg-config.exe")
-endif()
-
-# Our pkg-config search path to append to the system-wide search path
-#
-# Some development packages (like giflib) have no pkg-config integration. We provide
-# our own pkg-config files for system-wide packages in extra/missing
-#
-if (WIN32)
-    set(SAIL_PKGCONFIG_PATH "${PROJECT_SOURCE_DIR}/extra/missing/pkgconfig/${CMAKE_SYSTEM_NAME}\;${PROJECT_SOURCE_DIR}/extra/B/lib/pkgconfig")
-else()
-    set(SAIL_PKGCONFIG_PATH "${PROJECT_SOURCE_DIR}/extra/missing/pkgconfig/${CMAKE_SYSTEM_NAME}:${PROJECT_SOURCE_DIR}/extra/B/lib/pkgconfig")
-endif()
+if (NOT SAIL_VCPKG)
+    if (WIN32)
+        set(PKG_CONFIG_EXECUTABLE "${PROJECT_SOURCE_DIR}/extra/bin/pkg-config.exe")
+    endif()
 
-set(ENV_PKG_CONFIG_PATH $ENV{PKG_CONFIG_PATH})
-if (ENV_PKG_CONFIG_PATH)
+    # Our pkg-config search path to append to the system-wide search path
+    #
+    # Some development packages (like giflib) have no pkg-config integration. We provide
+    # our own pkg-config files for system-wide packages in extra/missing
+    #
     if (WIN32)
-        set(ENV{PKG_CONFIG_PATH} "${ENV_PKG_CONFIG_PATH}\;${SAIL_PKGCONFIG_PATH}")
+        set(SAIL_PKGCONFIG_PATH "${PROJECT_SOURCE_DIR}/extra/missing/pkgconfig/${CMAKE_SYSTEM_NAME}\;${PROJECT_SOURCE_DIR}/extra/B/lib/pkgconfig")
     else()
-        set(ENV{PKG_CONFIG_PATH} "${ENV_PKG_CONFIG_PATH}:${SAIL_PKGCONFIG_PATH}")
+        set(SAIL_PKGCONFIG_PATH "${PROJECT_SOURCE_DIR}/extra/missing/pkgconfig/${CMAKE_SYSTEM_NAME}:${PROJECT_SOURCE_DIR}/extra/B/lib/pkgconfig")
     endif()
-else()
-    set(ENV{PKG_CONFIG_PATH} ${SAIL_PKGCONFIG_PATH})
-endif()
 
-find_package(PkgConfig REQUIRED)
+    set(ENV_PKG_CONFIG_PATH $ENV{PKG_CONFIG_PATH})
+    if (ENV_PKG_CONFIG_PATH)
+        if (WIN32)
+            set(ENV{PKG_CONFIG_PATH} "${ENV_PKG_CONFIG_PATH}\;${SAIL_PKGCONFIG_PATH}")
+        else()
+            set(ENV{PKG_CONFIG_PATH} "${ENV_PKG_CONFIG_PATH}:${SAIL_PKGCONFIG_PATH}")
+        endif()
+    else()
+        set(ENV{PKG_CONFIG_PATH} ${SAIL_PKGCONFIG_PATH})
+    endif()
+
+    find_package(PkgConfig REQUIRED)
+endif()
 
 # Common configuration file
 #
@@ -221,20 +235,27 @@ configure_file("${PROJECT_SOURCE_DIR}/dist/win/sail.iss" "${PROJECT_BINARY_DIR}/
 # Configure subdirs
 #
 
-find_package(SDL2)
-set(SAIL_SDL_EXAMPLE OFF)
-
 add_subdirectory(src/libsail-common)
 add_subdirectory(src/libsail)
 add_subdirectory(src/sail-codecs)
 add_subdirectory(src/bindings/c++)
-add_subdirectory(examples/c/sail-convert)
-add_subdirectory(examples/c/sail-probe)
-if (SDL2_FOUND)
-    set(SAIL_SDL_EXAMPLE ON)
-    add_subdirectory(examples/c/sail-sdl-viewer)
+
+if (SAIL_BUILD_EXAMPLES)
+    add_subdirectory(examples/c/sail-convert)
+    add_subdirectory(examples/c/sail-probe)
+
+    find_package(SDL2)
+    set(SAIL_SDL_EXAMPLE OFF)
+
+    if (SDL2_FOUND)
+        set(SAIL_SDL_EXAMPLE ON)
+        add_subdirectory(examples/c/sail-sdl-viewer)
+    endif()
+endif()
+
+if (SAIL_BUILD_TESTS)
+    add_subdirectory(tests)
 endif()
-add_subdirectory(tests)
 
 # Installation
 #
@@ -270,6 +291,7 @@ message("* CMake module link flags:     ${CMAKE_MODULE_LINKER_FLAGS}")
 message("*")
 message("* SAIL version:                ${PROJECT_VERSION}")
 message("* Developer mode:              ${SAIL_DEV}")
+message("* VCPKG mode:                  ${SAIL_VCPKG}")
 message("* SDL example:                 ${SAIL_SDL_EXAMPLE}")
 message("*")
 message("* Install prefix:              ${CMAKE_INSTALL_PREFIX}")
@@ -278,9 +300,8 @@ message("* INCLUDEDIR:                  ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_
 message("* DATADIR:                     ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATAROOTDIR}")
 message("*")
 message("* Colored output:              ${SAIL_COLORED_OUTPUT}${SAIL_COLORED_OUTPUT_CLARIFY}")
-message("* Enabled codecs:              ${CODECS}")
-message("* Enabled conditional codecs:  ${ENABLED_CONDITIONAL_CODECS}")
-message("* Disabled conditional codecs: ${DISABLED_CONDITIONAL_CODECS}")
+message("* Enabled codecs:              ${ENABLED_CODECS}")
+message("* Disabled codecs:             ${DISABLED_CODECS}")
 message("* Default read output format:  ${SAIL_DEFAULT_READ_OUTPUT_PIXEL_FORMAT}")
 message("*")
 message("***************************************")

FAQ.md

@@ -9,7 +9,8 @@ Table of Contents
   * [Can I implement an image decoding codec in C\+\+?](#can-i-implement-an-image-decoding-codec-in-c)
   * [Does SAIL preload all codecs in the initialization routine?](#does-sail-preload-all-codecs-in-the-initialization-routine)
   * [How does SAIL look for codecs?](#how-does-sail-look-for-codecs)
-    * [Windows](#windows)
+    * [Windows (VCPKG port)](#windows-vcpkg-port)
+    * [Windows (standalone build)](#windows-standalone-build)
     * [Unix (including macOS)](#unix-including-macos)
   * [I'd like to reorganize the standard SAIL folder layout on Windows](#id-like-to-reorganize-the-standard-sail-folder-layout-on-windows)
   * [I moved SAIL codecs\. How can I point SAIL to the new location?](#i-moved-sail-codecs-how-can-i-point-sail-to-the-new-location)
@@ -76,9 +77,14 @@ However, you can preload them explicitly with `sail_init_with_flags(SAIL_FLAG_PR
 
 ## How does SAIL look for codecs?
 
-Codecs paths search algorithm (first found path wins):
+Codecs path search algorithm (first found path wins):
 
-### Windows
+### Windows (VCPKG port)
+1. `SAIL_CODECS_PATH` environment variable
+2. `<SAIL DEPLOYMENT FOLDER>\sail\codecs`
+3. Hardcoded `SAIL_CODECS_PATH` in config.h
+
+### Windows (standalone build)
 1. `SAIL_CODECS_PATH` environment variable
 2. `<SAIL DEPLOYMENT FOLDER>\lib\sail\codecs`
 3. Hardcoded `SAIL_CODECS_PATH` in config.h
@@ -89,21 +95,31 @@ Codecs paths search algorithm (first found path wins):
 
 Additionally, `SAIL_MY_CODECS_PATH` environment variable is always searched so you can load your own codecs from there.
 
+On Windows, `sail.dll location` and `<FOUND PATH>/lib` are the only places where codecs DLL dependencies are searched. No other paths are searched.
+Use WIN32 API `AddDllDirectory` to add your own DLL dependencies search path.
+On other platforms, `<FOUND PATH>/lib` is added to the DLL search path.
+
 ## I'd like to reorganize the standard SAIL folder layout on Windows
 
 You can surely do that. However, with the standard layout SAIL detects the codecs' location automatically.
 If you reorganize the standard SAIL folder layout, you'll need to specify the new codecs' location by
-setting the `SAIL_CODECGS_PATH` environment variable.
+setting the `SAIL_CODECS_PATH` environment variable.
 
 ## I moved SAIL codecs. How can I point SAIL to the new location?
 
 Set the `SAIL_CODECS_PATH` environment variable to a desired location of the prebuilt SAIL codecs.
-`SAIL_CODECS_PATH/lib` is added to the DLL search path, so you can store DLL dependencies there.
+
+On Windows, `sail.dll location` and `SAIL_CODECS_PATH/lib` are the only places where codecs DLL dependencies are searched. No other paths are searched.
+Use WIN32 API `AddDllDirectory` to add your own DLL dependencies search path.
+On other platforms, `SAIL_CODECS_PATH/lib` is added to the DLL search path.
 
 ## How can I point SAIL to my custom codecs?
 
 Set the `SAIL_MY_CODECS_PATH` environment variable to a desired location of your custom SAIL codecs.
-`SAIL_MY_CODECS_PATH/lib` is added to the DLL search path, so you can store DLL dependencies there.
+
+On Windows, `sail.dll location` and `SAIL_MY_CODECS_PATH/lib` are the only places where codecs DLL dependencies are searched. No other paths are searched.
+Use WIN32 API `AddDllDirectory` to add your own DLL dependencies search path.
+On other platforms, `SAIL_MY_CODECS_PATH/lib` is added to the DLL search path.
 
 ## Describe the high-level APIs