From 6c8c426f9ec6f7541e58b9fae1f496b85c6e6aa4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gonzalo=20Garramu=C3=B1o?= Date: Fri, 20 Oct 2023 18:03:45 -0300 Subject: [PATCH] Updated README.html. --- README.html | 281 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 215 insertions(+), 66 deletions(-) diff --git a/README.html b/README.html index d8df61909..b470c701d 100644 --- a/README.html +++ b/README.html @@ -1,6 +1,15 @@ -

License Build Status Donate

+

mrv2

-

mrv2 is an open source professional player and review tool for vfx, animation and computer graphics.

+

mrv2 is an open source professional player and review tool for vfx, +animation and computer graphics.

Contents:

  • Running mrv2

    Pre-built binaries

    -

    If you are looking for pre-built binaries for Windows, Linux or macOS (Intel), they can be found in:

    +

    If you are looking for pre-built binaries for Windows, Linux or macOS +(Intel), they can be found in:

    GitHub

    or in its mirror site at:

    -

    SourceForge

    -

    The source forge site also hosts beta builds (nightly builds with the latest changes).

    +

    SourceForge

    +

    The source forge site also hosts beta builds (nightly builds with the +latest changes):

    +

    SourceForge +Betas

    Compatibility

    -

    mrv2 binaries run on Windows 8.1+, RedHat 8.1+ or Ubuntu 20.04+ and macOS 11.0+.

    +

    mrv2 binaries run on Windows 8.1+, RedHat 8.1+ or Ubuntu 20.04+ and +macOS 11.0+.

    Notes on installation

      sudo dpkg -i mrv2-v0.7.8-Linux-amd64.tar.gz

    On Red Hat (Rocky Linux, etc), you would install it with:

      sudo rpm -i mrv2-v0.7.8-Linux-amd64.tar.gz
    -

    Once you install it, you can run mrv2 by just typing mrv2 in the shell, as a symlink to the executable is placed in /usr/bin. The installers will also associate file extensions and install an icon for easy starting up in the Desktop icon of the user that installed it. For running mrv2 with the icon, you need to select it and use the right mouse button to open the menu and choose Allow Launch.

    -

    If you lack sudo permissions in your organization, you should download the .tar.gz file and you can uncompress it with:

    +

    Once you install it, you can run mrv2 by just typing mrv2 in the +shell, as a symlink to the executable is placed in /usr/bin. The +installers will also associate file extensions and install an icon for +easy starting up in the Desktop icon of the user that installed it. For +running mrv2 with the icon, you need to select it and use the right +mouse button to open the menu and choose Allow Launch.

    +

    If you lack sudo permissions in your organization, you should +download the .tar.gz file and you can uncompress it with:

      tar -xf mrv2-v0.7.8-Linux-amd64.tar.gz
    -

    That will create a folder in the direcory you uncompress it from. You can then run mrv2 by using the mrv2.sh shell script in the bin/ subdirectory.

    +

    That will create a folder in the direcory you uncompress it from. You +can then run mrv2 by using the mrv2.sh shell script in the bin/ +subdirectory.

    Features

    -

    The source code is written in C++17 and uses CMake for the build system, with some bash scripts for auxiliary tasks.
    -The core of the playback engine is a custom version of tlRender (www.github.com/darbyjohnston/tlRender.git).

    +

    The source code is written in C++17 and uses CMake for the build +system, with some bash scripts for auxiliary tasks.
    +The core of the playback engine is a custom version of tlRender +(www.github.com/darbyjohnston/tlRender.git).

    Currently supported:

    Building

    Building with Docker

    -

    On Linux, if you have Docker installed with your user as part of the docker group, you can just build mrv2 with:

    +

    On Linux, if you have Docker installed with your user as part of the +docker group, you can just build mrv2 with:

    ./runme_docker.sh
    -

    The resulting installers will be placed in a new packages/ directory of the root of mrv2. The docker images are compatible with RedHat 8.1 and Ubuntu 20.04.

    +

    The resulting installers will be placed in a new packages/ directory +of the root of mrv2. The docker images are compatible with RedHat 8.1 +and Ubuntu 20.04.

    Dependencies

    RedHat

    #
@@ -151,14 +204,23 @@ 
    macOS

    Windows

    -

    Additional dependencies are downloaded and built automatically by the CMake superbuild script. For a list of non-system libraries that mrv2 depends on and their licenses, please refer to mrv2/docs/Legal. The system dependencies for each OS is listed below.

    -

    The only special requirement is installing a new copy of cmake than the one that ships with MSVC19. If building the NSIS installer, you need to place the root of mrv2 in a path that has less than 20 characters, like:

    +

    Additional dependencies are downloaded and built automatically by the +CMake superbuild script. For a list of non-system libraries that mrv2 +depends on and their licenses, please refer to mrv2/docs/Legal. The +system dependencies for each OS is listed below.

    +

    The only special requirement is installing a new copy of cmake than +the one that ships with MSVC19. If building the NSIS installer, you need +to place the root of mrv2 in a path that has less than 20 characters, +like:

         /D/code/applications

    Building mrv2

    Clone the repository:

    @@ -171,32 +233,56 @@

    Building mrv2

    cd mrv2 ./runme.sh -

    The script is a superbuild script that will download all needed dependencies required. It will create a build and a:

    +

    The script is a superbuild script that will download all needed +dependencies required. It will create a build and a:

    BUILD-KERNEL-ARCH/BUILDTYPE/install

    directory where all files shall reside.

    -

    Make sure you meet the basic dependencies for your platform. See Dependencies.

    -

    The runme.sh sript will output its progress to the terminal and also save itt in:

    +

    Make sure you meet the basic dependencies for your platform. See Dependencies.

    +

    The runme.sh sript will output its progress to the terminal and also +save itt in:

    BUILD-KERNEL-ARCH/BUILDTYPE/compile.log.
    -

    The default is to build with all cores in all the Operating Systems. If you want more or less cores pass another number to any of the runme*.sh scripts. For example, to build with 4 cores, you can do:

    +

    The default is to build with all cores in all the Operating Systems. +If you want more or less cores pass another number to any of the +runme*.sh scripts. For example, to build with 4 cores, you can do:

    ./runme.sh -j 4
    -

    Later, if you just want to build mrv2 quickly (runme quick mnemonic) without running through all the dependencies, run:

    +

    Later, if you just want to build mrv2 quickly (runme quick mnemonic) +without running through all the dependencies, run:

    ./runmeq.sh
    -

    Later, to just build FLTK, tlRender and mrv2 (runme three mnemonic), run;

    +

    Later, to just build FLTK, tlRender and mrv2 (runme three mnemonic), +run;

    ./runmet.sh

    Debug builds

    -

    All runme.sh scripts support two additional parameters. For a debug build, you would do:

    +

    All runme.sh scripts support two additional parameters. For a debug +build, you would do:

    ./runme.sh debug

    To clean up the directory, run a debug build with 8 cores, run:

    ./runme.sh clean debug -j 8

    Building on Windows

    -

    For windows, in addition to Visual Studio, you will need a new and fresh copy of Msys. There is a .bat file included in the distribution (in windows/bat), which needs to be modified to the path of Visual Studio (2019 by default), the optional Windows SDK (none by default) and your copy of Msys.

    -

    As a convernience for Windows users, DLLs, includes and .lib files for FFmpeg and liblcms2 libraries are provided in mrv2’s windows/win64 directory. The libintl and libiconv libraries are taken from the MSys64 repositories as pre-flight check with the bin/install_libintl_window.sh script (part of runme.sh).

    -

    If you unset LCMS2_ROOT in windows/envvars/envvars.sh, the library will be compiled.

    +

    For windows, in addition to Visual Studio, you will need a new and +fresh copy of Msys. There is a .bat file included in the distribution +(in windows/bat), which needs to be modified to the path of Visual +Studio (2019 by default), the optional Windows SDK (none by default) and +your copy of Msys.

    +

    As a convernience for Windows users, DLLs, includes and .lib files +for FFmpeg and liblcms2 libraries are provided in mrv2’s windows/win64 +directory. The libintl and libiconv libraries are taken from the MSys64 +repositories as pre-flight check with the bin/install_libintl_window.sh +script (part of runme.sh).

    +

    If you unset LCMS2_ROOT in windows/envvars/envvars.sh, the library +will be compiled.

    CMake build options

    -

    The main runme.sh script supports passing CMake flags to it and allows turning on or off some options of mrv2. You must pass them like:

    +

    The main runme.sh script supports passing CMake flags to it and +allows turning on or off some options of mrv2. You must pass them +like:

    -D TLRENDER_USD=OFF

    Currently, the flags supported are:

    +++++ @@ -242,48 +328,90 @@

    CMake build options

    Name
    -

    Building FFmpeg as GPL or LGPL

    +

    Building FFmpeg as GPL or +LGPL

    If you pass -gpl or -lpgl to the runme.sh script, like:

    ./runme.sh -gpl
    -

    The build system will compile FFmpeg as GPL or LGPL on all platforms. The default is to build a LGPL version of FFmpeg as that complies with the BSD binary distribution license. The LGPL version of FFmpeg, however, does not come with libx264, which means you cannot save movie files with the H264 codec. On Windows, if you don’t specify neither -gpl nor -lgpl, the pre-compiled LGPL binaries are used.

    -

    The GPL version of FFmpeg does not have that restriction and it will compile libx264 on all platforms.

    +

    The build system will compile FFmpeg as GPL or LGPL on all platforms. +The default is to build a LGPL version of FFmpeg as that complies with +the BSD binary distribution license. The LGPL version of FFmpeg, +however, does not come with libx264, which means you cannot save movie +files with the H264 codec. On Windows, if you don’t specify neither -gpl +nor -lgpl, the pre-compiled LGPL binaries are used.

    +

    The GPL version of FFmpeg does not have that restriction and it will +compile libx264 on all platforms.

    Running mrv2

    macOS and Linux

    -

    If you have a bin directory in your $HOME (ie. ~/bin ), the build scripts will create a symlink there. So you should add ~/bin to your PATH in your .bashrc or .zshrc.

    -

    Assuming you complied mrv2 with the ~/bin directory already created, then to start mrv2 then you’d do:

    +

    If you have a bin directory in your $HOME (ie. ~/bin ), the build +scripts will create a symlink there. So you should add ~/bin to your +PATH in your .bashrc or .zshrc.

    +

    Assuming you complied mrv2 with the ~/bin directory already created, +then to start mrv2 then you’d do:

    export PATH=~/bin:$PATH  # no need if you add this line to your .bashrc
 mrv2

    and to run the debug build.

    export PATH=~/bin:$PATH  # no need if you add this line to your .bashrc
 mrv2-dbg
    -

    If you compiled mrv2 without bin directory in your HOME directory, you can start it from the BUILD directory with the mrv2.sh script, like:

    +

    If you compiled mrv2 without bin directory in your HOME directory, +you can start it from the BUILD directory with the mrv2.sh script, +like:

    BUILD-Linux-amd64/Release/install/bin/mrv2.sh

    Windows

    -

    On Windows, we cannot create symbolic links, so in Msys you need to type the whole path to the install. That is, for example:

    +

    On Windows, we cannot create symbolic links, so in Msys you need to +type the whole path to the install. That is, for example:

    BUILD-Msys-amd64/Release/install/bin/mrv2.exe
    -

    If you like to work command line, you should add the whole path to the mrv2.exe to your path. In Msys, you can add it to the .bashrc like shown on macOS and Linux.

    -

    For cmd.exe or PowerShell, on the Windows taskbar, right-click the Windows icon and select System. In the Settings window, under Related Settings, click Advanced system settings. On the Advanced tab, click Environment Variables. Find the PATH environment variable and add the full path to mrv2.exe.

    +

    If you like to work command line, you should add the whole path to +the mrv2.exe to your path. In Msys, you can add it to the .bashrc like +shown on macOS and Linux.

    +

    For cmd.exe or PowerShell, on the Windows taskbar, right-click the +Windows icon and select System. In the Settings window, under Related +Settings, click Advanced system settings. On the Advanced tab, click +Environment Variables. Find the PATH environment variable and add the +full path to mrv2.exe.

    For working with a GUI, after the build is done, you should do:

    cd BUILD-Msys-amd64/Release/install/bin/  # or similar
 explorer .
    -

    And in the explorer directory that it will open, you should create a shortcut with the RMB to the mrv2.exe. Once that is done, you can drag and rename the shortcut to your Desktop to have it handy. Note that if you will not be developing mrv2, you should instead proceed to Packaging.

    +

    And in the explorer directory that it will open, you should create a +shortcut with the RMB to the mrv2.exe. Once that is done, you can drag +and rename the shortcut to your Desktop to have it handy. Note that if +you will not be developing mrv2, you should instead proceed to Packaging.

    Tutorials

    -

    Besides the basic API documentation included, there is a special channel on youtube.com where you can find some tutorials on its basic use:

    -

    Video Tutorials

    +

    Besides the basic API documentation included, there is a special +channel on youtube.com where you can find some tutorials on its basic +use:

    +

    Video +Tutorials

    Documenting

    -

    Currently, the documentation is generated automatically from the translations. To do so, you must run:

    +

    Currently, the documentation is generated automatically from the +translations. To do so, you must run:

    ./runmeq.sh -t doc

    Translating

    -

    mrv2 can support multiple natural language translations. Currently, English and Spanish are supported. The translation system used is gettext so familiarity with it is desired (albeit not essential). The translations reside in mrv2/po and follow internationalization language code files, like es.po (for Spanish) or de.po (for German).

    -

    To create such a file for a new language, open the file cmake/translations.cmake and add a language international code to this line:

    +

    mrv2 can support multiple natural language translations. Currently, +English and Spanish are supported. The translation system used is +gettext so familiarity with it is desired (albeit not essential). The +translations reside in mrv2/po and follow internationalization language +code files, like es.po (for Spanish) or de.po (for German).

    +

    To create such a file for a new language, open the file +cmake/translations.cmake and add a language international code to this +line:

    set( LANGUAGES es ) # add a new language code inside the parenthesis, like "de".

    Then, run:

    ./runmeq.sh -t po
    -

    If there’s no .po file for that language yet, gettext’s msginit command will be run for you. You may be asked for your email address as part of the process.

    +

    If there’s no .po file for that language yet, gettext’s msginit +command will be run for you. You may be asked for your email address as +part of the process.

    Go to mrv2/po/{lang}.po where lang is the language you added.

    and edit the text. Make sure to change the charset to UTF-8.

    -

    Note that you should use an editor that can write in Unicode (UTF-8) to write non-Occidental languages.

    -

    You need to edit “msgstr” strings and leave “msgid” untouched as a reference. If the comment has a “fuzzy” string it means gettext tried to guess the translation, but it will not use it. Remove the fuzzy qualifier and change the “msgstr” string. Note that if the “msgid” has new-lines you need to match them too. Refer to the gettext manual for further information.

    +

    Note that you should use an editor that can write in Unicode (UTF-8) +to write non-Occidental languages.

    +

    You need to edit “msgstr” strings and leave “msgid” untouched as a +reference. If the comment has a “fuzzy” string it means gettext tried to +guess the translation, but it will not use it. Remove the fuzzy +qualifier and change the “msgstr” string. Note that if the “msgid” has +new-lines you need to match them too. Refer to the gettext manual for +further information.

    Once you are ready to test your translation, run:

    ./runmeq.sh -t mo

    That will create the .mo files for your language.

    @@ -292,28 +420,49 @@

    If you compiled mrv2

    ./runmeq.sh -t install

    or just:

    ./runmeq.sh
    -

    and that will place the .mo files in the: BUILD−OS-ARCH/BUILD_TYPE/install/share/locale directory.

    -

    If you add or remove strings as part of your code changes, you may want to regenerate the .pot files after a while, before calling -t mo. To do so:

    +

    and that will place the .mo files in the: BUILD−OS-ARCH/BUILD_TYPE/install/share/locale +directory.

    +

    If you add or remove strings as part of your code changes, you may +want to regenerate the .pot files after a while, before calling -t mo. +To do so:

    ./runmeq.sh -t pot
    -

    Note that this change is dramatic as your commits of the code changes will get mangled with all the .pot/.po comments, preventing a clean PR (Pull Request) on github.com.

    +

    Note that this change is dramatic as your commits of the code changes +will get mangled with all the .pot/.po comments, preventing a clean PR +(Pull Request) on github.com.

    If you did not compile mrv2

    -

    Manually copy the .mo to your installed mrv2 directory. Make sure the VERSION matches.

    +

    Manually copy the .mo to your installed mrv2 directory. Make sure the +VERSION matches.

    cp mrv2/share/locale/${lang}/LC_MESSAGES/mrv2-v${VERSION}.mo ${installed_location of mrv2)/hare/locale/${lang}/LC_MESSAGES/

    Translating on Windows

    -

    On Windows, besides the text of mrv2, you also need to translate the text for the NSIS .exe installer.

    -

    You can do it by editing the cmake/nsis/mrv2_translations.nsh file. Just follow the examples in that file.

    +

    On Windows, besides the text of mrv2, you also need to translate the +text for the NSIS .exe installer.

    +

    You can do it by editing the cmake/nsis/mrv2_translations.nsh file. +Just follow the examples in that file.

    Packaging

    -

    Once you build mrv2 and tested that it runs, you might want to create a package for distribution. On macOS, this is a .dmg file. On Linux it is a RPM, DEB or TGZ file. On Windows it is a ZIP or an NSIS EXE installer.

    +

    Once you build mrv2 and tested that it runs, you might want to create +a package for distribution. On macOS, this is a .dmg file. On Linux it +is a RPM, DEB or TGZ file. On Windows it is a ZIP or an NSIS EXE +installer.

    To do so, from the main dir of mrv2, you have to do:

    ./runmeq.sh -t package

    For all architectures, the installers will be stored in:

    packages/

    That is the root directory of mrv2.

    Developing

    -

    If you want to become a developer, first familiarize yourself with the build process. Then clone the repository to your github account and send PRs. If you become an avid developer, you can then request access to the main repository.

    -

    One additional thing that you will need for making commits to the repository, is:

    +

    If you want to become a developer, first familiarize yourself with +the build process. Then clone the repository to your github account and +send PRs. If you become an avid developer, you can then request access +to the main repository.

    +

    One additional thing that you will need for making commits to the +repository, is:

    clang-format
    -

    This is part of the LLVM project, you can download it from your usual repositories (apt, brew, etc.), or from:

    -

    LLVM Main Download Page

    -

    This utility verifies previous to a commit that all the C++ formatting follows the standard used in mrv2.

    -

    You might also want to get Doxygen so as to get the source code documentation in docs/Doxygen.

    +

    This is part of the LLVM project, you can download it from your usual +repositories (apt, brew, etc.), or from:

    +

    LLVM Main Download +Page

    +

    This utility verifies previous to a commit that all the C++ +formatting follows the standard used in mrv2.

    +

    You might also want to get Doxygen so as to get the source code +documentation in docs/Doxygen.