OGRE-Next Debian packaging
==========================

User information
================

OGRE-Next packages in Debian are designed to work together with OGRE 1.x
packages. Please use the OGRE-Next name for buildsystems:

 * pkg-config
  `pkg-config --cflags --libs OGRE-Next OGRE-Next-Hlms`

 * CMake
  ```
  find_package(OGRE-Next REQUIRED)
  ...
  target_link_libraries(TARGET ${OGRE-Next_LIBRARIES}
                               ${OGRE-Next_HlmsPbs_LIBRARIES}
                               ${OGRE-Next_HlmsUnlit_LIBRARIES}
                               ...)
  target_include_directories(TARGET PUBLIC ${OGRE-Next_INCLUDE_DIRS}
                                           ${OGRE-Next_HlmsPbs_INCLUDE_DIRS}
                                           ${OGRE-Next_HlmsUnlit_INCLUDE_DIRS}
                                           ...)
 ```

Developer information
=====================

Background
----------
OGRE-Next project started as the 2.x branch of the OGRE project becoming a
independent project during the development of 2.1 OGRE branch. The code base
reflects well this history since most of the names, paths, documents, comments
or other artifacts still refers to the project as OGRE.

OGRE 1.x in Debian
------------------
OGRE has been in Debian since version 1.7. The packaging uses versioned -dev
package names (i.e libogre-1.12-dev, libogre-1.9-dev, etc). The packages however
can not be installed together since upstream uses the same system paths and
names. No big problem since the project is the same and upgrades should be
handled as usual inside Debian.

OGRE-Next and OGRE together
---------------------------
Being OGRE-Next a totally independent project from OGRE, providing different
features, there are some use cases where developers support and use both, OGRE
and OGRE-Next, at the same time
(i.e: https://github.com/ignitionrobotics/ign-rendering#features).

Upstream OGRE-Next sources are not prepared yet to support this use case. Please
note that upstream agrees completely on modifying the code to support this use
case:

 - Proposal: make the project side-by-side installable with Ogre (1.x)
   - https://github.com/OGRECave/ogre-next/issues/232
 - Proposal: renaming libraries in OGRE-Next: libOgre -> libOgreNext
   - https://github.com/OGRECave/ogre-next/issues/259

Main problem is the lack of human resources in Upstream to change code. Some
Debian maintainers (i.e Jose Luis Rivero) and other developers are helping with
this effort but could take long time.
(i.e: https://github.com/OGRECave/ogre-next/pull/234)

Debian modifications to support OGRE-Next and OGRE together
-----------------------------------------------------------
The needed changes to support parallel installations of OGRE and OGRE-Next
packages are not very complex. They will be submitted to upstream as soon as
other PRs are being merged but meanwhile they are done using Debian packaging
mechanisms:

1. Rename libOgre* libraries to libOgreNext*
   * Changes in source code to produce new names are done in
     d/patches/use-ogrenext-names-for-libs.patch

2. Relocate plugins moved from /usr/lib/$(DEB_HOST_MULTIARCH)/OGRE to
   to /usr/lib/$(DEB_HOST_MULTIARCH)/OGRE-Next. Plugins need to keep their
   current names.
   * Moved in d/rules

3. Relocate headers moving from /usr/include/OGRE/ /usr/include/OGRE-Next/
   * No upstream support for this yet, done by moving files before_dh_install in
     rules file.

3. Change pkg-config files to accommodate these changes
   * Fixes in d/rules file to set OGRE-Next as name
   * Missing includes in d/patches

4. Change CMake files to accommodate these changes
   * Replace FindOGRE.cmake with custom OGRE-NextConfig.cmake file in d/extras:
     Config file is really a copy of FindOGRE.cmake produced by the buildsystem
     with changes in variable names: OGRE -> OGRE-Next and the addition to the
     CMAKE_MODULE_PATH of CMAKE_CURRENT_LIST_DIR to make other cmake files to be
     found.
   * Relocate all CMake modules to standard location in d/rules

ABI policy upstream
===================

Upstream has declared that ABI could be broken even in patch releases, see
https://github.com/OGRECave/ogre-next/issues/232#issuecomment-939187318. To
handle with this the library package names include the whole version to avoid
crashes due to possible ABI changes.

Recommendations from https://bugs.debian.org/989344 are also followed, packaging
the libraries in their own packages.

For the future, there is a proposal to bring some API/ABI stability to the project:
https://github.com/OGRECave/ogre-next/issues/258
