### Install RAKE from Source

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Install RAKE by downloading the source tarball, extracting it, and running the install script. This method is for manual installation from source.

```bash
ruby install.rb
```

--------------------------------

### Configure Automatic Build Script

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/Building.for.Windows.md

Adjust variables in the setup script to match your build requirements, such as target architecture and installation directory.

```bash
ARCHITECTURE=64
INSTALL_DIR=$HOME/mxe
PARALLEL=
```

--------------------------------

### Install RAKE

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Install the RAKE gem using the gem command. This is the standard method for installing Rake.

```bash
gem install rake
```

--------------------------------

### Install CompTree Gem

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/comp_tree-1.1.3/README.rdoc

Use this command to install the CompTree gem. Alternatively, you can install from a downloaded .tgz file using 'rake install'.

```bash
% gem install comp_tree
```

--------------------------------

### Install DRAKE

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Install the DRAKE gem using the gem command. This command installs the drake executable.

```bash
gem install drake
```

--------------------------------

### Install nlohmann-json with wsjcpp

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Use this command to install the latest version of nlohmann-json with wsjcpp. You can specify a different branch or tag by changing ':develop'.

```shell
wsjcpp install "https://github.com/nlohmann/json:develop"
```

--------------------------------

### Package manager integration (Conan)

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Example of how to use the library with the Conan package manager. This simplifies dependency management.

```cmake
include(conanbuildinfo.cmake)
conan_basic_setup()
```

--------------------------------

### Example of untranslatable strings

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/doc/development.md

Command line options and their fixed values should not be translated. Placeholders for values like filenames can be translated.

```text
--stereo-mode <TID:[none|both]>
```

```text
--attach-file filename
```

--------------------------------

### Execute Automatic Build Script

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/Building.for.Windows.md

Run the provided script from the MKVToolNix source directory to automatically download, compile, and install all necessary libraries.

```bash
./packaging/windows/setup_cross_compilation_env.sh
```

--------------------------------

### Install nlohmann-json with MacPorts

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Use this command to install the nlohmann-json package if you are using MacPorts.

```shell
sudo port install nlohmann-json
```

--------------------------------

### Simple Rakefile Example

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Define a default task that depends on a test task, which in turn runs a Ruby unit test file. This demonstrates basic Rakefile syntax.

```ruby
task :default => [:test]

task :test do
  ruby "test/unittest.rb"
end
```

--------------------------------

### Running Rake Tasks

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Use 'rake' to execute tasks if rake is installed. If not, use 'ruby -Ilib bin/rake'.

```shell
rake                  # If you have a version of rake installed
ruby -Ilib bin/rake   # If you do not have a version of rake installed.
```

--------------------------------

### Run Rake Test Suite

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/drake-0.9.2.0.3.1/README.rdoc

Execute the unit and functional tests included with Rake. Ensure 'flexmock' and 'session' gems are installed and navigate to the project directory.

```bash
flexmock gem install
session gem install
cd rake

```

--------------------------------

### Define and Compute Functions with CompTree

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/comp_tree-1.1.3/README.rdoc

This snippet demonstrates how to define functions with arguments, constants, and then compute a result using parallel threads. Ensure the 'comp_tree' gem is installed.

```ruby
require 'comp_tree'

CompTree.build do |driver|

  # Define a function named 'area' taking these two arguments.
  driver.define(:area, :width, :height) { |width, height|
    width*height
  }
  
  # Define a function 'width' which takes a 'border' argument.
  driver.define(:width, :border) { |border|
    7 + border
  }
  
  # Ditto for 'height'.
  driver.define(:height, :border) { |border|
    5 + border
  }
  
  # Define a constant function 'border'.
  driver.define(:border) {
    2
  }
  
  # Compute the area using up to four parallel threads.
  puts driver.compute(:area, 4)
  # => 63

  # We've done this computation.
  puts((7 + 2)*(5 + 2))
  # => 63
end
```

--------------------------------

### Check and Create MP3 Packetizer

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/doc/development.md

This example demonstrates how to check if a specific audio demuxer is requested and if the reader has already created packetizers before creating a new MP3 packetizer. It's specific to MP3 due to the format's single-track limitation.

```cpp
// Check if the audio demuxer with ID 0 is requested.
    // Also make sure that the number of packetizers this reader has created is
    // still 0.
    if (!demuxing_requested('a', 0) || (NPTZR() != 0))
      return;

    // Create the actual packetizer.
    add_packetizer(new mp3_packetizer_c(this, m_ti, mp3header.sampling_frequency, mp3header.channels, false));

    // Inform the user.
    show_packetizer_info(0, PTZR0);
```

--------------------------------

### Timestamp Format v2 Example

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/examples/example-timestamps-v2.txt

This is an example of the timestamp format v2. The first line must be the format identifier. Subsequent lines contain timestamps in milliseconds for each frame. Empty lines and lines starting with '#' are ignored. Only dots ('.') are accepted as decimal points.

```text
# The very first line MUST have this format.

# As you can see empty lines and other lines starting with '#' are ignored.

# The remaining lines simply contain the timestamp in ms for the following
# frame. The number can be a floating point number, but it doesn't have to
# be. Note that only dots ('.') are accepted as the decimal point, not
# commas!

# White spaces are ignored.

# You must give at least as many timestamp lines here as the track contais
# frames. Otherwise mkvmerge will complain, and the results might not be
# what you expect.

# Example for 10 consecutive frames at 25fps:
0
40.0
80.0
120
160
200
240
280
320
360

# No need to use floats, but you can if you want. Now some more frames which
# are spaced a bit more.
460
560
660
760
860
960
1060
```

--------------------------------

### Get Previous UTF-8 Code Point with utf8::prior

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/utf8-cpp/README.md

Decrements the iterator to the start of the previous UTF-8 code point and returns its value. Use with caution as it's slower than forward iteration and may skip superfluous trail octets.

```cpp
template <typename octet_iterator>
uint32_t prior(octet_iterator& it, octet_iterator start);

```

```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
unsigned char* w = twochars + 3;
int cp = prior (w, twochars);
assert (cp == 0x65e5);
assert (w == twochars);

```

--------------------------------

### Compile and Run Unit Tests

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Instructions for building the project with tests enabled and executing the test suite. This process may download external test data.

```shell
mkdir build
cd build
cmake .. -DJSON_BuildTests=On
cmake --build .
ctest --output-on-failure
```

--------------------------------

### Pkg-config integration

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Demonstrates how to use `pkg-config` to find and link the JSON library. This is useful for projects not using CMake.

```bash
gcc main.cpp -o my_executable $(pkg-config --cflags --libs nlohmann_json)
```

--------------------------------

### Serialize and Deserialize JSON to Binary Formats

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Demonstrates serializing a JSON value to BSON, CBOR, MessagePack, and UBJSON, and then deserializing it back to JSON. Ensure the correct format functions are used for each binary type.

```cpp
// create a JSON value
json j = R"({\"compact\": true, \"schema\": 0})"_json;

// serialize to BSON
std::vector<std::uint8_t> v_bson = json::to_bson(j);

// 0x1B, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00

// roundtrip
json j_from_bson = json::from_bson(v_bson);

// serialize to CBOR
std::vector<std::uint8_t> v_cbor = json::to_cbor(j);

// 0xA2, 0x67, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xF5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_cbor = json::from_cbor(v_cbor);

// serialize to MessagePack
std::vector<std::uint8_t> v_msgpack = json::to_msgpack(j);

// 0x82, 0xA7, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xC3, 0xA6, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_msgpack = json::from_msgpack(v_msgpack);

// serialize to UBJSON
std::vector<std::uint8_t> v_ubjson = json::to_ubjson(j);

// 0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D

// roundtrip
json j_from_ubjson = json::from_ubjson(v_ubjson);

```

--------------------------------

### CMake External Integration

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Use find_package to locate an installed nlohmann_json and link against the imported target. Requires nlohmann_json to be installed.

```cmake
# CMakeLists.txt
find_package(nlohmann_json 3.2.0 REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```

--------------------------------

### BAD Example: Function Affecting State

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/comp_tree-1.1.3/README.rdoc

This example demonstrates a function that has a side effect by modifying an external 'accumulator'. This is discouraged as it can lead to unpredictable results in parallel computations.

```ruby
driver.define(:area, :width, :height) { |width, height|
  accumulator.add "more data"
  width*height
}
```

--------------------------------

### Configure MKVToolNix with Cross-Compiler

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/Building.for.Windows.md

Configure the MKVToolNix build system, specifying the cross-compilation host and paths to Qt tools. Ensure the host specification matches the MXE_TARGETS used previously.

```bash
cd $HOME/path/to/mkvtoolnix-source
host=x86_64-w64-mingw32.static
qtbin=$HOME/mxe/usr/${host}/qt5/bin
./configure \
  --host=${host} \
  --enable-static-qt \
  --with-moc=${qtbin}/moc --with-uic=${qtbin}/uic --with-rcc=${qtbin}/rcc \
  --with-boost=$HOME/mxe/usr/${host}
```

--------------------------------

### BAD Example: Function Depending on Undefined State

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/rake.d/vendor/comp_tree-1.1.3/README.rdoc

This example shows a function that incorrectly depends on an external 'offset' variable not declared as an argument. This can lead to undefined results when computed in parallel.

```ruby
driver.define(:area, :width, :height) { |width, height|
  width*height - offset
}
```

--------------------------------

### Skipping Non-Reproducible Tests

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Command to skip tests that modify installed files, ensuring reproducibility.

```shell
ctest -LE not_reproducible
```

--------------------------------

### Run MKVToolNix Unit Tests

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/README.md

After configuring and building MKVToolNix, use the 'rake' command to build and execute the unit tests.

```bash
rake tests:run_unit
```

--------------------------------

### Getting file size with mm_file_io_c

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/doc/development.md

Retrieve the size of the file opened by mm_file_io_c using the get_size() method.

```cpp
int64_t size = file->get_size();
```

--------------------------------

### Opening a file for reading with mm_file_io_c

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/doc/development.md

Instantiate mm_file_io_c to open a file for reading. The constructor takes the file name. Use mm_file_io_cptr for automatic memory management.

```cpp
mm_file_io_cptr file(new mm_file_io_c(file_name));
```

--------------------------------

### CMake Embedded Integration

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Embed the library by adding its source directory to your project using add_subdirectory. This avoids external installation requirements.

```cmake
# Typically you don't care so much for a third party library's tests to be
# run from your own project's code.
set(JSON_BuildTests OFF CACHE INTERNAL "")

# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")

# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended consequences that will break the build.  It's generally
# discouraged (although not necessarily well documented as such) to use
# include(...) for pulling in other CMake projects anyways.
add_subdirectory(nlohmann_json)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```

--------------------------------

### JSON Array Comparison and Utility Functions

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Provides examples of comparing a JSON array to a literal string representation and using utility functions like `size()`, `empty()`, `type()`, and `clear()`. Type checker functions are also shown.

```cpp
// comparison
j == R"(["foo", 1, true, 1.78])"_json;  // true

// other stuff
j.size();     // 4 entries
j.empty();    // false
j.type();     // json::value_t::array
j.clear();    // the array is empty again

// convenience type checkers
j.is_null();
j.is_boolean();
j.is_number();
j.is_object();
j.is_array();
j.is_string();
```

--------------------------------

### Get include flags with pkg-config

Source: https://github.com/mbunkus/mkvtoolnix/blob/main/lib/nlohmann-json/README.md

Use this command with pkg-config to generate the necessary include flags for using nlohmann_json in bare Makefiles.

```shell
pkg-config nlohmann_json --cflags
```