From 405fa911ad974eeaf3c3769820b7c4a0c59f0099 Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Sun, 5 Aug 2018 19:46:52 -0700 Subject: [PATCH] edits to READMEs --- IlmBase/README.md | 66 +++++++++-------- OpenEXR/README | 77 -------------------- OpenEXR/README.CVS | 16 ----- OpenEXR/README.OSX | 57 --------------- OpenEXR/README.git | 16 ----- OpenEXR/README.md | 144 +++++++++++++++++++++++++++++++++++++ OpenEXR/README.namespacing | 83 --------------------- README.md | 51 ++++++++----- 8 files changed, 215 insertions(+), 295 deletions(-) delete mode 100644 OpenEXR/README delete mode 100644 OpenEXR/README.CVS delete mode 100644 OpenEXR/README.OSX delete mode 100644 OpenEXR/README.git create mode 100644 OpenEXR/README.md delete mode 100644 OpenEXR/README.namespacing diff --git a/IlmBase/README.md b/IlmBase/README.md index 8e9ea21b4b..7f71c08e85 100644 --- a/IlmBase/README.md +++ b/IlmBase/README.md @@ -1,6 +1,8 @@ The IlmBase Libraries ===================== +The IlmBase libraries include the following: + * **Half** - a class that encapsulates our 16-bit floating-point format. * **IlmThread** - a thread abstraction library for use with OpenEXR and @@ -12,6 +14,9 @@ and other useful 2D and 3D math functions. * **Iex** is an exception-handling library. +In addition, the distribution also includes confidence test libaries: +**HalfTest**, **IexTest**, and **ImathTest**. + If you have questions about using the IlmBase libraries, you may want to join our developer mailing list. See http://www.openexr.com for details. @@ -19,8 +24,9 @@ details. License ------- -IlmBase, including all contributions, is released under the modified -BSD license. Please see the ``LICENSE`` file for the legal fine print. +IlmBase, including all contributions, is released under a modified BSD +license. Please see the ``LICENSE`` file accompanying the distribution +for the legal fine print. Building and Installation ------------------------- @@ -29,7 +35,7 @@ You can build IlmBase using either **autoconf** or **cmake**. #### Building with **autoconf** -First, ensure that **autoconf** is instaleld. Download and install it +First, ensure that **autoconf** is installed. Download and install it from https://www.gnu.org/software/autoconf/autoconf.html. To bootstrap the build process: @@ -53,13 +59,12 @@ To build the libraries: make make install - #### Building with **cmake** First, ensure that **cmake** is installed. Download and install it from https://cmake.org/download. -To bootstrap the cmake build process: +To bootstrap the **cmake** build process: cmake -DCMAKE_INSTALL_PREFIX= make @@ -69,8 +74,8 @@ To bootstrap the cmake build process: To generate Visual Studio solution files and build the libraries: -1. Launch a command window, navigate to the IlmBase folder with - CMakeLists.txt,and type command: +1. Launch a command window, navigate to the ``IlmBase`` folder containing + ``CMakeLists.txt``, and type the command: setlocal del /f CMakeCache.txt @@ -78,15 +83,15 @@ To generate Visual Studio solution files and build the libraries: -G "Visual Studio 10 Win64" ..\ilmbase -2. Navigate to IlmBase folder in Windows Explorer, open ILMBase.sln - and build the solution. When it build successfully, right click - INSTALL project and build. It will install the output to the path +2. Navigate to ``IlmBase`` folder in Windows Explorer, open ``ILMBase.sln`` + and build the solution. When it builds successfully, right click + ``INSTALL project`` and build. It will install the output to the path you set up at the previous step. -3. Go to http://www.zlib.net and download zlib +3. Go to http://www.zlib.net and download zlib. -4. Launch a command window, navigate to the OpenEXR folder with - CMakeLists.txt, and type command: +4. Launch a command window, navigate to the ``OpenEXR`` folder containing + ``CMakeLists.txt``, and type the command: setlocal del /f CMakeCache.txt @@ -97,10 +102,10 @@ To generate Visual Studio solution files and build the libraries: -G "Visual Studio 10 Win64" ^ ..\openexr -5. Navigate to OpenEXR folder in Windows Explorer, open OpenEXR.sln - and build the solution. When it build successfully, right click - INSTALL project and build. It will install the output to the path - you set up at the previous step. +5. Navigate to ``OpenEXR`` folder in Windows Explorer, open + ``OpenEXR.sln`` and build the solution. When it builds + successfully, right click ``INSTALL project`` and build. It will + install the output to the path you set up at the previous step. #### Building on **macOS** @@ -125,7 +130,7 @@ For more information on universal builds, see: http://developer.apple.com/documentation/Porting/Conceptual/PortingUNIX/compiling/chapter_4_section_3.html -Earlier releases of IlmBase included an +Earlier releases of **IlmBase** included an ``--enable-osx-universal-binaries`` switch, which specifies a two-way universal build: Intel and PowerPC, 32-bit only. This is still available, but deprecated in favor of the more flexible @@ -142,7 +147,7 @@ For example, if you are building on Mac OS X 10.4, but you need access to features that were introduced in Mac OS X 10.5, you can build against the Mac OS X 10.5 versions of system libraries and headers. -You can choose to build IlmBase with a specific SDK using the +You can choose to build **IlmBase** with a specific SDK using the ``--enable-osx-sdk`` switch. For example: ./configure --enable-osx-sdk=MacOSX10.5.sdk @@ -155,6 +160,10 @@ For more information on sysroots, see: http://developer.apple.com/documentation/DeveloperTools/gcc-4.2.1/gcc/Directory-Options.html +#### Header Installation Directory + +All include files needed to use the OpenEXR libraries are installed in the +``OpenEXR`` subdirectory of the install prefix, e.g. ``/usr/local/include/OpenEXR``. Namespaces ---------- @@ -208,8 +217,8 @@ namespace is discouraged. This ensures that code will continue to compile with customised or future versions of the library, which may have a different internal namespace. -Similarily, for other namespaces in the libraries: ``Iex``, -``IlmThread`` and ``IlmImf``. +Similarily, for other namespaces in the libraries: **Iex**, +**IlmThread** and **IlmImf**. Note that this scheme allows existing code to compile without modifications, since the 'old' namespaces ``Imath``, ``Iex``, @@ -224,8 +233,8 @@ This is achieved via the following, in the Imath case: using namespace IMATH_INTERNAL_NAMESPACE; } -This is included in all header files in the Imath library and similar ones -are present for the libraries ``Iex``, ``IlmThread`` and ``IlmImf``. +This is included in all header files in the **Imath** library and similar ones +are present for the libraries **Iex**, **IlmThread** and **IlmImf**. The only exception to this is where user code has forward declarations of objects in the ``Imf`` namespace, as these will forward declare @@ -233,7 +242,7 @@ symbols in an incorrect namespace These forward declarations should be removed, and replaced with: - #include , + #include which forward-declares all types correctly. @@ -257,11 +266,12 @@ Type: make check -to run the IlmBase confidence tests. They should all pass; if you -find a test that does not pass on your system, please let us know. +to run the IlmBase confidence tests (HalfTest, IexTest, and +ImathTest). They should all pass; if you find a test that does not +pass on your system, please let us know. All include files needed to use the IlmBase libraries are installed in -the OpenEXR subdirectory of the install prefix, +the ``OpenEXR`` subdirectory of the install prefix, e.g. ``/usr/local/include/OpenEXR``. @@ -270,6 +280,6 @@ Using IlmBase in Your Applications On systems with support for **pkg-config**, use ``pkg-config --cflags IlmBase`` for the C++ flags required to compile against IlmBase -headers; and `pkg-config --libs IlmBase`` for the linker flags +headers; and ``pkg-config --libs IlmBase`` for the linker flags required to link against IlmBase libraries. diff --git a/OpenEXR/README b/OpenEXR/README deleted file mode 100644 index 7038b1ce66..0000000000 --- a/OpenEXR/README +++ /dev/null @@ -1,77 +0,0 @@ -ABOUT THE OPENEXR LIBRARIES ----------------------------- - -IlmImf is our "EXR" file format for storing 16-bit FP images. Libraries in -this package depend on the IlmBase library. - -See the IlmImfExamples directory for some code that demonstrates how -to use the IlmImf library to read and write OpenEXR files. The doc -directory contains some high-level documentation and history about the -OpenEXR format. - -If you have questions about using the OpenEXR libraries, you may want -to join our developer mailing list. See http://www.openexr.com for -details. - - -LICENSE -------- - -The OpenEXR source code distribution is free software. See the file -named COPYING (included in this distribution) for details. - - -BUILDING OPENEXR ----------------- - -Building OpenEXR requires the IlmBase and the zlib library. - -You can obtain the source code for zlib from: - - http://www.zlib.net - -If you're building OpenEXR on a Windows platform, see README.win32 for -instructions on how to build OpenEXR. The remainder of this file -applies only to GNU/Linux or other UNIX-like systems. - -After installing the required libraries, to build OpenEXR on -GNU/Linux or other UNIX-like systems, do this: - -./configure -make -make install - -unless you obtained IlmBase directly from git, in which case you -should first read README.git - - -Please type : - -./configure --help - -for a list of options in relation to building IlmBase libraries. In -particular, peruse README.namespaces for information regarding the -use of namespaces in IlmBase and OpenEXR. - -See README.OSX for details on building OpenEXR in MacOS X. - -Do `make check` to run the OpenEXR confidence tests. They should all -pass; if you find a test that does not pass on your system, please let -us know. - -Other UNIX variants haven't been tested, but should be easy to build. -Let us know if you're having problems porting OpenEXR to a particular -platform. - -All include files needed to use the OpenEXR libraries are installed in the -OpenEXR subdirectory of the install prefix, e.g. /usr/local/include/OpenEXR. - - -USING OPENEXR IN YOUR APPLICATIONS ----------------------------------- - -On systems with support for pkg-config, use `pkg-config --cflags -OpenEXR` for the C++ flags required to compile against OpenEXR -headers; and `pkg-config --libs OpenEXR` for the linker flags required -to link against OpenEXR libraries. - diff --git a/OpenEXR/README.CVS b/OpenEXR/README.CVS deleted file mode 100644 index 90a4fa3d10..0000000000 --- a/OpenEXR/README.CVS +++ /dev/null @@ -1,16 +0,0 @@ -If you're using OpenEXR from CVS, you should run the bootstrap script -to create the auto* files. It's a good idea to run this whenever you -update OpenEXR from CVS. - -Then run './configure' and make. - -Note that the configure.ac file requires a fairly new version of -automake. If you get this error message: - -running aclocal ... -aclocal: configure.ac: 142: macro `AM_CFLAGS' not found in library -aclocal: configure.ac: 143: macro `AM_CXXFLAGS' not found in library -failed! - -you should upgrade your automake to version 1.6 or better. - diff --git a/OpenEXR/README.OSX b/OpenEXR/README.OSX deleted file mode 100644 index 646646d42d..0000000000 --- a/OpenEXR/README.OSX +++ /dev/null @@ -1,57 +0,0 @@ -OpenEXR on MacOS X ------------------- - -Building OpenEXR on MacOS X is just like building it on GNU/Linux. -Follow the instructions in the README file under BUILDLING OPENEXR, -but see below re: shared libraries. - -Missing gnu automake tools on Mac OS X 10.8+ ------------------- -Later versions of OS X ,10.8+, do not, by default have all the necessary -tools for building. In particular, Autoconf and Automake may be missing. - -The following commands will download and install the necessary components: - -cd ~/myDevLoc -curl -OL http://ftpmirror.gnu.org/autoconf/autoconf-2.64.tar.gz -tar xzf autoconf-2.64.tar.gz -cd autoconf-2.64 -./configure --prefix=~/myDevLoc/autotools-bin -make; make install - -cd ~/myDevLoc -curl -OL http://ftpmirror.gnu.org/automake/automake-1.12.tar.gz -tar xzf automake-1.12.tar.gz -cd automake-1.12 -./configure --prefix=~/myDevLoc/autotools-bin -make; make install - -cd ~/myDevLoc -curl -OL http://ftpmirror.gnu.org/libtool/libtool-2.4.tar.gz -tar xzf libtool-2.4.tar.gz -cd libtool-2.4 -./configure --prefix=~/myDevLoc/autotools-bin -make; make install - - -You may want to export the installation path for your convenience. -Finally, make sure that you have installed the command line tools for XCode. - - -Universal Builds on Mac OS X ------------------- - -On OS X 10.4, you can build universal binaries by passing -'--enable-osx-universal-binaries --disable-dependency-tracking' to the -configure script. The default is *not* to build universal binaries. - - -Shared libraries ----------------- - -OpenEXR requires the "flat namespace" option when built as a shared -library. You may have problems trying to use OpenEXR shared libraries -with applications that expect OS X's two-level namespace. We have not -tested the shared libs extensively, though they appear to work with -exrdisplay and exrheader, but use them at your own risk. We will -support two-level namespace shared libs in a future release. diff --git a/OpenEXR/README.git b/OpenEXR/README.git deleted file mode 100644 index d963e725b9..0000000000 --- a/OpenEXR/README.git +++ /dev/null @@ -1,16 +0,0 @@ -If you're using IlmBase from github, you should run the bootstrap script -to create the auto* files. It's a good idea to run this whenever you -update IlmBase from github. - -Then run './configure' and make. - -Note that the configure.ac file requires a fairly new version of -automake. If you get this error message: - -running aclocal ... -aclocal: configure.ac: 142: macro `AM_CFLAGS' not found in library -aclocal: configure.ac: 143: macro `AM_CXXFLAGS' not found in library -failed! - -you should upgrade your automake to version 1.6 or better. - diff --git a/OpenEXR/README.md b/OpenEXR/README.md new file mode 100644 index 0000000000..4b727b392b --- /dev/null +++ b/OpenEXR/README.md @@ -0,0 +1,144 @@ +The OpenEXR Libraries +===================== + +The OpenEXR module contains the following: + +* **IlmImf** - the core library that implements the "EXR" file format. +* **IlmImfUtil** - related utilities. +* **IlmImfExamples** - code that demonstrates how +to use the IlmImf library to read and write OpenEXR files. +* **doc** - high-level documentation and history about the OpenEXR +format. +* **exr2aces** - +* **exrbuild** +* **exrenvmap** +* **exrmakepreview** +* **exrmaketiled** +* **exrmultipart** +* **exrmultiview** +* **exrstdattr** + +In addition, the distribution also includes confidence tests: + +* **IlmImfTest** - basic confidence test. +* **IlmImfUtilTest** - huge input resilience test. +* **IlmImfFuzzTest** - damaged input resilience test. + +If you have questions about using the OpenEXR libraries, you may want +to join our developer mailing list. See http://www.openexr.com for +details. + +License +------- + +IlmBase, including all contributions, is released under a modified BSD +license. Please see the ``LICENSE`` file accompanying the distribution +for the legal fine print. + +Dependencies +------------ + +Building OpenEXR requires IlmBase and the [zlib](https://zlib.net) library. + +Building and Installation +------------------------- + +You can build OpenEXR using either **autoconf** or **cmake**. + +#### Building with **autoconf** + +First, ensure that **autoconf** is installed. Download and install it +from https://www.gnu.org/software/autoconf/autoconf.html. + +To bootstrap the build process: + + ./bootstrap + +To create Makefiles via **autoconf**: + + ./configure + +For help with useful build options: + + ./configure --help + +In particular, arguments of note include: + +* ``--prefix=`` - a directory into which + to install the headers and libraries. By default, headers and + libraries are installed into ``/usr/local``. + +* ``--with-ilmbase-prefix=`` - the direction + into which the IlmBase headers and libraries have been installed, if + not ``/usr/local``. + +* ``--enable-imfexamples`` - build IlmImf example program. + +To build the libraries: + + make + make install + +#### Building with **cmake** + +First, ensure that **cmake** is installed. Download and install it +from https://cmake.org/download. + +To bootstrap the **cmake** build process: + + cmake -DCMAKE_INSTALL_PREFIX= + make + make install + +#### Building on Windows using **cmake** + +#### Building on **macOS** + +**macOS** supports multiple architectures. By default, IlmBase will be +built for the system doing the building. For example, if you build +IlmBase on an Intel system, the libraries will be built for Intel. + +See the ``README`` file in the IlmBase library for details. + +#### Header Installation Directory + +All include files needed to use the OpenEXR libraries are installed in the +``OpenEXR`` subdirectory of the install prefix, e.g. ``/usr/local/include/OpenEXR``. + +Namespaces +---------- + +The IlmBase and OpenEXR libraries implement user-configurable +namespaces, which makes it possible to deal with multiple versions of +these libraries loaded at runtime. + +See the ``README`` file in the IlmBase library for details. + +Tests +----- + +Type: + + make check + +to run the IlmBase confidence tests (HalfTest, IexTest, and +ImathTest). They should all pass; if you find a test that does not +pass on your system, please let us know. + +Two of the confidence tests are not configured by default, because +they can take hours to run, but can be enabled via options to the +``configure`` script: + +* ``--enable-imffuzztest`` - build damaged input resilience test +* ``--enable-imfhugetest`` - build huge input resilience test + +Using IlmBase in Your Applications +---------------------------------- + +On systems with support for **pkg-config**, use ``pkg-config --cflags +OpenEXR`` for the C++ flags required to compile against OpenEXR +headers; and ``pkg-config --libs OpenEXR`` for the linker flags +required to link against OpenEXR libraries. + + + diff --git a/OpenEXR/README.namespacing b/OpenEXR/README.namespacing deleted file mode 100644 index ffae65f17e..0000000000 --- a/OpenEXR/README.namespacing +++ /dev/null @@ -1,83 +0,0 @@ ------------------------------------------------- - On the use of namespace in IlmBase and OpenEXR ------------------------------------------------- - -v2.0 of the code base introduces user configurable namespaces for -component libraries. This addition introduces the ability to deal with -multiple versions of these libraries loaded at runtime. -An example case: - Application is built with OpenEXR v1.7, but the required plugin - requires functionality from OpenEXR v2.0. - - By injecting the version number into the (mangled) symbols, via - the namespacing mechanism, and changing the soname, via the build - system, the developer can link his plugin against the v2.0 library - At run time the dynamic linker can load both the 1.7 and 2.0 - versions of the library since the library soname are different and - the symbols are different. - - -When building IlmBase or OpenEXR the following configure script options -are available: - --enable-namespaceversioning -and - --enable-customusernamespace - - - --- Internal Library Namespace -The option, --enable-namespaceversioning, controls the namespace that -is used in the library. Without an argument (see below) the library -will be built with a suffix made up of the major and minor versions. -For example, for version 2.0.0, the internal library namespaces will be -Imath_2_0, Iex_2_0, IlmThread_2_0 etc - -For additional flexibility and control, this option can take an additional -argument in which case the internal library namespace will be suffixed -accordingly. -For example: - ./configure --enable-namespaceversioning=ILM -will result in the namespaces of the type Imath_ILM, Iex_ILM etc. - -This can be useful for completely isolating your local build. - -Code using the library should continue to use the namespace Imath, or for -greater portability IMATH_NAMESPACE, to refer to objects in libImath. -In particular, the explicit use of the internal namespace is discouraged. -This ensures that code will continue to compile with customised or future -versions of the library, which may have a different internal namespace. - -Similarily, for other namespaces in the libraries: Iex, IlmThread and IlmImf. - -Note that this scheme allows existing code to compile without modifications, -since the 'old' namespaces Imath, Iex, IlmThread and IlmImf continue to be -available, albeit in a slightly different form. -This is achieved via the following, in the Imath case: - namespace IMATH_INTERNAL_NAMESPACE {} - namespace IMATH_NAMESPACE - { - using namespace IMATH_INTERNAL_NAMESPACE; - } -This is included in all header files in the Imath library and similar ones -are present for the libraries Iex, IlmThread and IlmImf. - -The only exception to this is where user code has forward declarations of -objects in the Imf namespace, as these will forward declare symbols in an -incorrect namespace -These forward declarations should be removed, and replaced with - #include , -which forward-declares all types correctly. - - - --- Public/User Library Namespace -The option, --enable-customusernamespace, can override the namespace into -which we will 'export' the internal namespace. This takes an argument -that sets the name of the custom user namespace. -In the example above, IMATH_NAMESPACE could be resolved into something other -than Imath, say Imath_MySpecialNamespace. - -In nearly all cases, this will not be used as per the above discussion -regarding code compatibility. -Its presence is to provide a mechanism for not prohibiting the case when -the application must pass objects from two different versions of the library. diff --git a/README.md b/README.md index 889e35cf2b..b6adb7e6cb 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,9 @@ OpenEXR's features include: License ------- -OpenEXR, including all contributions, is released under the modified -BSD license. Please see the LICENSE file for the legal fine print. +OpenEXR, including all contributions, is released under a modified BSD +license. Please see the ``LICENSE`` file accompanying the distribution +for the legal fine print. OpenEXR Sub-modules ------------------- @@ -56,7 +57,7 @@ The OpenEXR distribution consists of the following sub-modules: * **OpenEXR_Viewers** - Standard image viewing programs * **Contrib** - Various plugins and utilities, contributed by the community. -Please see the README files of each of the individual directories for more information. +Please see the ``README`` files of each of the individual directories for more information. A collection of OpenEXR images is available from the adjacent repository [openexr-images](https://github.com/openexr/openexr-images). @@ -82,31 +83,45 @@ Building and Installation Download the latest release of OpenEXR from http://www.openexr.com/downloads.html. -Alternatively, you can download the latest release or the lastest development branch directly from http://github.com/openexr. +Alternatively, you can download the latest release or the lastest +development branch directly from http://github.com/openexr. -To build the OpenEXR binaries from source, compile and install the individual sub-models, according to the instructions in the respective README files. +To build the OpenEXR binaries from source, compile and install the +individual sub-models (IlmBase, PyIlmBase, OpenEXR, OpenEXR_Viewers), +according to the instructions in the respective ``README`` files. -Build and install the IlmBase module first, then build and install the OpenEXR module. Optionally, then build and install PyIlmBase, OpenEXR_Viewers, and Contrib. +Build and install the IlmBase module first, then build and install the +OpenEXR module. Optionally, then build and install PyIlmBase, +OpenEXR_Viewers, and Contrib. -The build system supports building via autoconf or cmake. See in README files in the IlmBase, PyIlmBase, OpenEXR, and OpenEXR_Viewers directories for specific instructions. +The build system supports building via autoconf or cmake. See in +``README`` files in the IlmBase, PyIlmBase, OpenEXR, and OpenEXR_Viewers +directories for specific instructions. -#### Building with CMake +#### Dependencies + +OpenEXR depends on [zlib](https://zlib.net). + +PyIlmBase depends on [boost-python](https://github.com/boostorg/python). -To build with CMake, OpenEXR has a few prerequisites. +In OpenEXR_Viewers: + +* **exrdisplay** depends on [fltk](http://www.fltk.org/index.php) +* **playexr** depends on [Cg](https://developer.nvidia.com/cg-toolkit) + +#### Building with CMake -* CMake 3.11 or newer -* zlib -* boost-python (if the python bindings are to be built) -* fltk (if the openexr viewer is to be built) -* Cg (if playexr is to be built) +To build with **cmake** requires **cmake** version 3.11 or newer. When these prerequisites are fulfulled, prepare the build environment. -In the root CMakeLists.txt file, or using a tools such as ccmake or cmake-gui, -configure the OpenEXR build. The options are detailed below. +In the root ``CMakeLists.txt`` file, or using a tools such as +**ccmake** or **cmake-gui**, configure the OpenEXR build. The options +are detailed below. -Create a build directory, cd into it, and run cmake to configure the build. -Select an appropriate generator, such as "Unix Makefiles", or "Visual Studio 15 2017 Win64". +Create a build directory, cd into it, and run **cmake** to configure +the build. Select an appropriate generator, such as "Unix Makefiles", +or "Visual Studio 15 2017 Win64". cmake -DCMAKE_INSTALL_PREFIX= -G "selected generator" -DCMAKE_PREFIX_PATH=