rbe-tebako 0.15.0

data/CONTRIBUTING.adoc

@@ -0,0 +1,294 @@
+= Contributing to Tebako
+
+The following are a set of conventions and guidelines that are relevant to
+contributors to the Tebako project. These guidelines are based on the
+contribution guidelines from the RNP project, as both projects are developed by
+Ribose.
+
+== Pull requests
+
+See also: https://github.com/thoughtbot/guides/tree/master/code-review[Thoughtbot's Code Review guide]
+
+Pull Requests should be used for any non-trivial changes. This presents an
+opportunity for feedback and allows the CI tests to complete prior to merging.
+
+The `main` branch should generally always be in a buildable and functional state.
+
+Pull Requests should be:
+
+* Focused. Do not include changes that are unrelated to the main purpose of the PR.
+
+* As small as possible. Sometimes large pull requests may be necessary for
+adding complex features, but generally they should be kept as small as possible
+to ensure a quick and thorough review process.
+
+* Related to a GH issue to which you are assigned. If there is none, file one
+(but search first!). This ensures there is no duplication of effort and allows
+for a discussion prior to beginning work. (This may not be necessary for PRs
+that are purely documentation updates)
+
+* Approved by **2** reviewers before merging.
+
+* Merged by a reviewer via the most appropriate method.
+
+== Branches
+
+Git branches should be used generously. Most branches should be topic branches,
+created for adding a specific feature or fixing a specific bug.
+
+Keep branches short-lived (treat them as disposable/transient) and try to avoid
+long-running branches.
+
+A good example of using a branch would be:
+
+* User `@joe` notices a bug where a NULL pointer is dereferenced. `@joe` creates GH issue `#500`.
+* He creates a new branch to fix this bug named `joe-500-fix-null-deref-in-function`.
+* Joe commits a fix for the issue to this new branch.
+* Joe creates a Pull Request to merge this branch into main.
+* Once merged, Joe deletes the branch since it is no longer useful.
+
+Branch names may vary but should be somewhat descriptive, with words separated
+by hyphens. It is also helpful to start the branch name with your GitHub
+username, to make it clear who created the branch and prevent naming conflicts.
+
+Remember that branch names may be preserved permanently in the commit history of
+`main`, depending on how they are merged.
+
+== Commits
+
+* Try to keep commits as small as possible. This may be difficult or impractical
+at times, so use your best judgment.
+
+* Each commit should be buildable and should pass all tests. This helps to
+ensure that git bisect remains a useful method of pinpointing issues.
+
+* Commit messages should follow 50/72 rule.
+
+* When integrating pull requests, merge function should be preferred over
+squashing. From the other hand, developers should squash commits and create
+meaningful commit stack before PR is merged into mainstream branch. Merging
+commits like "Fix build" or "Implement comments from code review" should be
+avoided.
+
+== Code conventions
+
+The Tebako project includes both C/C++ and Ruby code. Each has its own set of conventions.
+
+=== C/C++ code conventions
+
+==== Code formatting
+
+C/C++ code should be formatted using `clang-format` (v11.0.0), utilizing the
+`.clang-format` file included in the repository.
+
+==== Style guide for C/C++
+
+In order to keep the code base consistent, we should define and adhere to a single style.
+
+When in doubt, consult the existing code base.
+
+===== Naming
+
+The following are samples that demonstrate the style for naming different things in C/C++ code:
+
+* Functions: `some_function`
+* Variables: `some_variable`
+* Filenames: `file-name.c` `file-name.h`
+* Struct: `tebako_struct_t`
+* Typedefed Enums: `tebako_enum_t`
+* Enum Values: `TEBAKO_ENUM_VALUE = 1`
+* Constants (macro): `TEBAKO_BUFSIZ`
+
+===== General guidelines for C/C++
+
+Do:
+
+* Do use header guards (`#ifndef SOME_HEADER_H [...]`) in headers.
+* Do use `sizeof(variable)`, rather than `sizeof(type)`. Or `sizeof(*variable)` as appropriate.
+* Do use commit messages that close GitHub issues automatically, when
+applicable. `Fix XYZ. Closes #78.` See
+https://help.github.com/articles/closing-issues-via-commit-messages/[here].
+* Do declare functions `static` when they do not need to be referenced outside the current source file.
+* Do always use braces for conditionals, even if the block only contains a single statement.
++
+[source,c]
+--
+if (something) {
+  return val;
+}
+--
+
+* Do use a default failure (not success) value for `ret` variables. Example:
++
+[source,c]
+--
+rnp_result_t ret = RNP_ERROR_GENERIC;
+// ...
+
+return ret;
+--
+
+Do not:
+
+* Do not use the static storage class for local variables, *unless* they are constant.
++
+**Not OK**
++
+[source,c]
+--
+int somefunc() {
+  static char buffer[256];
+  //...
+}
+--
++
+**OK**
++
+[source,c]
+--
+int somefunc() {
+  static const uint16_t some_data[] = {
+    0x00, 0x01, 0x02, //...
+  };
+}
+--
+
+* Do not use `pragma`, and try to avoid `__attribute__` as well.
+* Do not use uninitialized memory. Try to ensure your code will not cause any errors in valgrind and other memory checkers.
+
+==== Documentation for C/C++
+
+Documentation is done in Doxygen comments format, which must be put in header files.
+
+Exceptions are static or having only definition functions -- it is not required to
+document them, however if they are documented then this should be done in the
+source file and using the @private tag.
+
+Comments should use doxygen markdown style, like the following example:
+
+[source,c]
+--
+/** Some comments regarding the file purpose, like 'Tebako filesystem utilities'
+ *  @file
+ *
+ *  This file contains functions and definitions related to the Tebako filesystem.
+ *  Ensure to document all public interfaces thoroughly.
+ */
+
+/** brief description of the sample function which does something, keyword 'brief' is omitted
+ *  Which may be continued here
+ *
+ *  After an empty line you may add detailed description in case it is needed. You may put
+ *  details about the memory allocation, what happens if function fails and so on.
+ *
+ *  @param param1 first parameter, null-terminated string which should not be NULL
+ *  @param param2 integer, some number representing something
+ *  @param size number of bytes available to store in buffer
+ *  @param buffer buffer to store results, may be NULL. In this case size can be used to
+ *                obtain the required buffer length
+ *  @return 0 if operation succeeds, or error code otherwise. If operation succeeds then buffer
+ *          is populated with the resulting data, and size contains the length of this data.
+ *          if error code is E_BUF_TOOSMALL then size will contain the required size to store
+ *          the result
+ **/
+rnp_result_t
+tebako_do_operation(const char *param1, const int param2, int *size, char *buffer);
+--
+
+=== Ruby code conventions
+
+==== Code formatting
+
+Ruby code should follow the style defined in the `.rubocop.yml` file included in
+the repository. We adhere to the Ruby community's conventions with some
+project-specific modifications defined in this file.
+
+==== Style guide for Ruby
+
+Ruby code should generally follow the Ruby Style Guide (https://rubystyle.guide/), with customizations specific to the Tebako project.
+
+===== Naming
+
+* Classes and Modules: `CamelCase`
+* Methods and Variables: `snake_case`
+* Constants: `SCREAMING_SNAKE_CASE`
+* Predicate methods (returning boolean): end with question mark `available?`
+* Dangerous methods (modifying `self` or arguments): end with exclamation mark `save!`
+* Private methods: `_leading_underscore` (or just use the `private` keyword)
+
+===== General guidelines for Ruby
+
+* Use 2 spaces for indentation, never tabs
+* Limit lines to 100 characters when possible
+* Use `def` with parentheses when there are parameters
+* Use parentheses for method calls with arguments
+* Never use `and`/`or` for control flow; use `&&`/`||` instead
+* Avoid multi-line ternary operators
+* Use `snake_case` for naming files and directories
+* Prefer string interpolation and template strings to string concatenation
+* Prefer double quotes for strings unless the string contains double quotes
+
+==== Documentation for Ruby
+
+Ruby code should be documented using YARD.
+
+[source,ruby]
+--
+# A person class to represent individuals
+class Person
+  # @return [String] the person's full name
+  attr_reader :name
+
+  # Creates a new person
+  #
+  # @param name [String] the person's full name
+  # @param age [Integer] the person's age in years
+  # @return [Person] a new instance of Person
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+
+  # Determines if the person is an adult
+  #
+  # @return [Boolean] true if the person is 18 or older
+  def adult?
+    @age >= 18
+  end
+end
+--
+
+=== Testing
+
+==== C/C++ testing
+:cpp: C++
+C/{cpp} code should have appropriate tests. Tests for C/{cpp} code should be:
+
+* Comprehensive, covering normal operation and error conditions
+* Written to validate both public API and internal functionality
+* Organized in logical test suites
+
+==== Ruby testing
+
+Ruby code should have RSpec tests. Tests for Ruby code should:
+
+* Follow the RSpec style guide
+* Use descriptive contexts and examples
+* Use appropriate RSpec matchers
+* Mock external dependencies when appropriate
+* Achieve high test coverage (as reported by the coverage tool)
+
+== Code of conduct
+
+The Tebako project has adopted the Contributor Covenant as its Code of Conduct.
+All contributors are expected to adhere to these guidelines to foster an open
+and welcoming community.
+
+For the full Code of Conduct, please refer to link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT.adoc].
+
+== References
+
+For more detailed guidelines, please refer to the RNP project's development guidelines:
+
+* RNP Code of Conduct: https://github.com/rnpgp/rnp/blob/main/docs/code-of-conduct.adoc
+* RNP Development Guide: https://github.com/rnpgp/rnp/blob/main/docs/develop.adoc

data/Gemfile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2023-2025 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of the Tebako project.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS
+# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rbe-tebako.gemspec
+gemspec

data/INSTALLATION.adoc

@@ -0,0 +1,233 @@
+= Tebako: Local Installation
+
+== General
+
+This document describes how to install Tebako locally on your machine.
+It covers installation on the following platforms:
+
+. Ubuntu (version 20.04)
+. Alpine (version 3.17)
+. macOS
+. Windows
+
+== Prerequisites
+
+=== Ubuntu 20.04
+
+==== GNU C/C++ 10+ or Clang C/C++ 12+
+
+[source,sh]
+----
+apt install -y gcc-10 g++-10
+update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
+update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
+----
+
+or
+
+[source,sh]
+----
+apt install -y clang-12
+update-alternatives --install /usr/bin/clang clang /usr/bin/clang-12 150
+update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-12 150
+----
+
+==== CMake version 3.20+
+
+Tebako requires CMake version 3.20 or later.
+
+If such a CMake version is not available as a default package, set it up as follows.
+
+.Installing CMake 3.20+
+[source,sh]
+----
+apt-get remove --purge --auto-remove cmake
+apt-get update
+apt-get install -y software-properties-common lsb-release curl
+apt-get clean all
+curl https://apt.kitware.com/kitware-archive.sh | bash
+apt-get install cmake
+----
+
+==== Other Development Tools and Libraries
+
+[source,sh]
+----
+apt-get -y install sudo git curl build-essential pkg-config bison flex autoconf  \
+   binutils-dev libevent-dev acl-dev libfmt-dev libjemalloc-dev libiberty-dev    \
+   libdouble-conversion-dev liblz4-dev liblzma-dev libssl-dev libunwind-dev      \
+   libboost-filesystem-dev libboost-program-options-dev libboost-system-dev      \
+   libboost-iostreams-dev libboost-date-time-dev libboost-context-dev            \
+   libboost-regex-dev libboost-thread-dev libbrotli-dev libdwarf-dev libelf-dev  \
+   libgoogle-glog-dev libffi-dev libgdbm-dev libyaml-dev libncurses-dev          \
+   libreadline-dev libutfcpp-dev ruby-dev ruby-bundler
+----
+
+=== Alpine 3.17
+
+==== APK Packages
+
+Run the following command to install all prerequisites.
+
+[source,sh]
+----
+apk --no-cache --upgrade add build-base cmake git bash autoconf boost-static   \
+   boost-dev flex-dev bison make binutils-dev libevent-dev acl-dev sed python3 \
+   pkgconfig lz4-dev openssl-dev zlib-dev xz ninja zip unzip curl libdwarf-dev \
+   libunwind-dev gflags-dev elfutils-dev libevent-static openssl-libs-static   \
+   lz4-static xz-dev zlib-static libunwind-static acl-static tar libffi-dev    \
+   gdbm-dev yaml-dev yaml-static ncurses-dev ncurses-static readline-dev       \
+   readline-static p7zip ruby-dev gcompat gettext-dev gperf brotli-dev         \
+   brotli-static jemalloc-dev fmt-dev xz-static
+----
+
+=== macOS
+
+==== General
+
+There are several prerequisites that need to be installed on macOS for Tebako
+to work correctly.
+
+The following instructions apply to:
+
+* macOS 13 (Ventura) through macOS 15 (Sequoia)
+
+==== Homebrew Packages
+
+We use Homebrew to install the necessary packages on macOS.
+
+Tebako provides a `Brewfile` at the repository root, allowing you to install
+all dependencies using the `brew bundle` command.
+
+[source,sh]
+----
+brew bundle
+----
+
+Alternatively, you can install the packages manually.
+
+[source,sh]
+----
+brew update
+brew install gnu-sed bash pkg-config bison flex binutils libffi gdbm zlib \
+  ncurses double-conversion boost jemalloc fmt glog libevent libsodium lz4 xz \
+  libyaml openssl@3
+----
+
+==== Bison 3+
+
+Tebako requires Bison 3 or later.
+
+On macOS 14, the default Bison version is 2.3, and the Homebrew formula is keg-only,
+meaning the full path to the Bison binary must be used.
+
+Run the following command prior to using Tebako, or add it to your shell profile.
+
+[source,sh]
+----
+export PATH="$(brew --prefix bison)/bin:$PATH"
+----
+
+==== jemalloc Library Build
+
+On macOS, the `libdwarfs` build script creates an additional `jemalloc` installation
+to satisfy linking requirements. However, this uses a static library.
+
+If `jemalloc` is built within an emulated environment (QEMU, Rosetta, etc.), there are known issues
+(link:https://github.com/jemalloc/jemalloc/issues/1997[jemalloc issue #1997])
+where `jemalloc` incorrectly detects the number of significant virtual address bits (`lg-vaddr`).
+
+These issues can be fixed by explicitly setting the `--with-lg-vaddr` parameter during the `jemalloc`
+build. However, Tebako does not automate this due to lack of sufficient test coverage.
+
+Instead, our build script accepts the `LG_VADDR` environment variable, which is passed as `--with-lg-vaddr=${LG_VADDR}`.
+
+The `LG_VADDR` parameter specifies the number of significant virtual address bits, which can
+vary based on CPU architecture and emulation status.
+
+This is a simple example script to set `LG_VADDR`.
+
+NOTE: This is provided for illustration only.
+
+[example]
+====
+[source,sh]
+----
+#!/bin/bash
+
+# Check the CPU architecture
+ARCH=$(uname -m)
+
+# Check if running under Rosetta 2 emulation
+if [[ "$ARCH" == "x86_64" && $(sysctl -n sysctl.proc_translated) == "1" ]]; then
+  echo "Running on Apple Silicon under Rosetta 2 emulation"
+  export LG_VADDR=39
+elif [[ "$ARCH" == "arm64" ]]; then
+  echo "Running on Apple Silicon"
+  export LG_VADDR=39
+else
+  echo "Running on Intel Silicon"
+  export LG_VADDR=48
+fi
+
+echo "Setting lg-vaddr to $LG_VADDR"
+----
+====
+
+=== Windows
+
+==== General
+
+The following instructions have been tested on:
+
+* Windows 10, 11
+* Windows Server 2019, 2022
+
+==== Ruby
+
+Ensure that you have long filenames enabled in Windows.
+https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later[long filenames enabled in Windows]. This is required for the majority of applications.
+
+To run Tebako, a Ruby development environment is required.
+The simplest option is to use the Ruby development environment provided by
+https://rubyinstaller.org[RubyInstaller].
+
+For example, Ruby+Devkit 3.4.10-1.
+
+==== MinGW ucrt64
+
+Enable MinGW ucrt64 and install the necessary packages.
+
+The `ridk` command originates from the RubyInstaller installation.
+
+[source,sh]
+----
+idk enable ucrt64
+pacman -S git tar bison flex pactoys
+bash -c "pacboy sync toolchain:p make:p cmake:p boost:p diffutils:p libevent:p double-conversion:p fmt:p glog:p dlfcn:p gtest:p autotools:p ncurses:p libyaml:p"
+----
+
+== Gem Installation
+
+Tebako is distributed as a Ruby gem. A Ruby environment is necessary.
+
+[source,sh]
+----
+gem install tebako
+----
+
+== Post-Install Setup (Not Generally Required)
+
+Tebako requires a post-install setup after gem installation, as described in
+link:README.adoc[README.adoc].
+
+Post-install setup is called automatically during the first packaging.
+Manual setup is only required if a pristine Tebako packaging environment is needed
+to implement a caching strategy.
+
+== License
+
+Copyright Ribose. All rights reserved.
+
+Tebako is released under the BSD 2-Clause License. See the
+link:LICENSE.md[LICENSE.md] file for details.

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2021-2025, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.