tebako 0.12.16 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90a79cb3c7cf5d46a64d7337c96dfeff2b2c1aa0bcc73ba6ef19a260fff8d2e8
-  data.tar.gz: 32dd49b7bca79dc56611dbc08c838bd211fd75c99b99d81df72f4962237ccc4e
+  metadata.gz: b76afc326826bf28f1e102114a95d5be16e3fb3ec8755830ad719c0c17da0244
+  data.tar.gz: fae51d705eedb1735426ca175ce89ccad509aaaf9fcb4436d5cef19d7ff7ac38
 SHA512:
-  metadata.gz: 9e8b56db99c71dc148ab2596cf9338babd50784f2a98a9361e101af8734801ccaa72d580575ebad7599faed6f66e0100fdf4c0f045d857581d0af58a194b1c0a
-  data.tar.gz: 0d63898d6c18e696a44fb31a15c76821b0dabbf9ccc69ea98437d2962a522eecec40ddd9277a3680cf3a23e2a8f8882c750e74e930f1e20224f25ed7d59e9f61
+  metadata.gz: ef50f9c470ce36732df94ec543feae0ec9ec27c8baa7f62043937ab8bef5cf07466ee613336d987d304b47e10cbbac5f4404f9b85a17f294e21002c3cb8fec13
+  data.tar.gz: 57390b1c83cbfad6d65b37a80f6d64cb5897c794113134284e1bf6a44efadbf746892cc2c980e17bafb12ccb508e3e45b799e5624f30555cc942349a38585c79

data/CMakeLists.txt

@@ -1,6 +1,6 @@
 # Copyright (c) 2021-2025 [Ribose Inc](https://www.ribose.com).
 # All rights reserved.
-# This file is a part of tebako
+# 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
@@ -178,7 +178,7 @@ string(CONCAT RUBY_API_VER ${RUBY_VER_BASE} ".0")
 #  list(GET LIBDWARFS_WR_VER_COMPONENTS 2 LIBDWARFS_WR_VER_PATCH)
 #  set (LIBDWARFS_WR_VER_M ${LIBDWARFS_WR_VER_MAJOR}.${LIBDWARFS_WR_VER_MINOR}.${LIBDWARFS_WR_VER_PATCH})
 #else(DWARFS_PRELOAD)
-def_ext_prj_g(DWARFS_WR "v0.9.7")
+def_ext_prj_g(DWARFS_WR "v0.10.1")
 #endif(DWARFS_PRELOAD)
 
 def_ext_prj_g(PATCHELF "65e14792061c298f1d2bc44becd48a10cbf0bc81")

data/CODE_OF_CONDUCT.adoc

@@ -0,0 +1,128 @@
+
+= Contributor covenant code of conduct
+
+== Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+== Our standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+== Enforcement responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+== Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+== Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+open.source@ribose.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+== Enforcement guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+=== 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+=== 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+=== 3. Temporary ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+=== 4. Permanent ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+== Attribution
+
+This Code of Conduct is adapted from the
+https://www.contributor-covenant.org[Contributor Covenant],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+https://github.com/mozilla/diversity[Mozilla's code of conduct enforcement ladder].
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

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

@@ -2,7 +2,7 @@
 
 # Copyright (c) 2023 [Ribose Inc](https://www.ribose.com).
 # All rights reserved.
-# This file is a part of tebako
+# 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

data/INSTALLATION.adoc

@@ -0,0 +1,231 @@
+= 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
+
+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.3.7-1.
+
+==== MinGW ucrt64
+
+Enable MinGW ucrt64 and install the necessary packages.
+
+The `ridk` command originates from the RubyInstaller installation.
+
+[source,sh]
+----
+ridk enable ucrt64
+pacman -S git tar bison flex toolchain make cmake \
+          boost diffutils libevent double-conversion \
+          fmt glog dlfcn gtest autotools ncurses libyaml
+----
+
+== 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.