tebako 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3673be08addf6a4b0dffb509d247cfe167d6de7f8948d612c91624bb2415f850
-  data.tar.gz: 9aab2d7554a9a124a4d23fed253fcd4046a0021bff79b6ba148622d97db7776f
+  metadata.gz: 78803d4ebbfe58cdf860a80c9ec60fe44a80e2d12bd695678a37c914f069948b
+  data.tar.gz: f13f3e254a4058044a7c84c03f07ebc3c5a07c3fc00eda1e4ced0e336326fa55
 SHA512:
-  metadata.gz: 0b4939849fe0053753fb847977eca8097978579a7c9c00c25db3536de46bd5387b768729646b12044629ee7bb1aded3076739c201b6e2ebf70f8cd90b3a9ad7b
-  data.tar.gz: 75b96fac44a38fafee73c8eba4f951f15d3b566ca979c1681be5610919602f9f7678b1878ac26847c9d5587ce47866c6f9a8a915d530e695db7c07e8dfe567f9
+  metadata.gz: f76bd6166857ebf239218e3871136142a6c158a5d568f019eb374ea694b9af07d342378ee23e3e760063049b3e84048a42a92ed5b0dc420957898aef7679dd64
+  data.tar.gz: 15c95e6dcb0f746f4708548b5ceda202552fd2c9ed6461d4f814707ddb9c80d6d58fddf00791437a26142eb9db703f4d3017bb47f74f55afeb1a78fc6e78c585

data/CMakeLists.txt

@@ -181,7 +181,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.8.3")
+def_ext_prj_g(DWARFS_WR "v0.9.2")
 #endif(DWARFS_PRELOAD)
 
 def_ext_prj_g(PATCHELF "65e14792061c298f1d2bc44becd48a10cbf0bc81")
@@ -406,24 +406,14 @@ else (${SETUP_MODE})
   set(CMAKE_CXX_STANDARD_REQUIRED ON)
   set(CMAKE_CXX_EXTENSIONS   OFF)
 
+# ...................................................................
+# Packaged filesystem
+
   add_custom_target(packaged_filesystem
     COMMAND ruby ${DEPS_BIN_DIR}/deploy.rb
     DEPENDS ${RUBY_PRJ}
     BYPRODUCTS ${DATA_BIN_FILE}
- )
-
-# ...................................................................
-# Packaged filesystem
-
-  #add_custom_target(packaged_filesystem
-    # No progress below is critical since in reporting mode mkdwarfs tries to work directly with terminal
-    # and it creates issues for stderr redirects (&2 > 1) used by Ninja and our test srcipts
-    # It may be fixable bit is very difficult to reproduce in test environment
-   # COMMAND ${DEPS_BIN_DIR}/mkdwarfs -o ${DATA_BIN_FILE} -i ${DATA_SRC_DIR} --no-progress
-   # #COMMAND ${CMAKE_COMMAND} -E touch ${DEPS_SRC_DIR}/tebako/tebako-fs.cpp
-   # DEPENDS setup source_filesystem
-   # VERBATIM
-  #)
+  )
 
   set(CMAKE_CXX_FLAGS "${RUBY_C_FLAGS}")
 

data/README.adoc

@@ -26,20 +26,23 @@ a bundled runtime into a single, performant, executable binary.
 
 == Architecture
 
-A Tebako-packaged binary is effectively a self-executing container-in-a-file.
+A Tebako package is effectively a self-executing container-in-a-file.
 
-The packaged binary contains the following components:
+The package contains the following components:
 
 * An on-file filesystem (OFFS) containing all the project files and
-dependencies in DwarFS format.
+dependencies in DwarFS format ("application")
 
-* A runtime environment that includes the necessary libraries and interpreters,
+* A runtime environment that includes the the necessary libraries and interpreters,
 with patched filesystem calls that redirect access of project files to the
-on-file filesystem.
+on-file filesystem ("runtime")
 
-* An executable loader that loads the on-file filesystem in memory and executes
-the project.
+Tebako is capable to create a single file that contains both runtime and
+application or place runtime and application to separate files. In the latter
+case the runtime can be used with different applications or versions of the same
+application.
 
+Please refer to `mode` option below that controls Tebako output.
 
 == Supported runtimes, platforms and architectures
 
@@ -72,19 +75,24 @@ architectures.
 ====
 Windows build caveats:
 
-* Tebako may face errors related to CMake path length limitations (https://gitlab.kitware.com/cmake/cmake/-/issues/25936).
-This error may affect not tebako itself but the gems that need to be package and use CMake to build native extensions.
-There is no workaround for this issue as it looks like is a limitation of the manifest used to build CMake executable.
+* Tebako may face errors related to CMake path length limitations
+(https://gitlab.kitware.com/cmake/cmake/-/issues/25936).
+This error may affect not Tebako itself but the gems that need to be package and
+use CMake to build native extensions.
+There is no workaround for this issue as it looks like is a limitation of the
+manifest used to build CMake executable.
 
-* MSys strip utility creates broken executable when tebako image is processed. Linking with '-s' flag produces unusable
-executables as well.
-Until this issue (https://github.com/tamatebako/tebako/issues/172) is resolved we plan to produce an Windows executable
-with debug information unstripped. You can opt to run 'strip -S' manually, it most cases it works.
+* MSys strip utility creates broken executable when Tebako image is processed.
+Linking with `-s` flag produces unusable executables as well.
+Until this issue (https://github.com/tamatebako/tebako/issues/172) is resolved
+we plan to produce a Windows executable with debug information unstripped. You
+can opt to run `strip -S` manually, it most cases it works.
 
 MacOS build caveats:
 
-* We saw clang compiler segmentaion fault when during packaging of very large projects with XCode 14.3.1
-This issue is not reproducible with XCode 15.0.1 or higher.
+* We saw `clang` compiler segmentation fault when during packaging of very large
+projects with XCode 14.3.1. This issue is not reproducible with XCode 15.0.1 or
+higher.
 ====
 
 
@@ -96,8 +104,9 @@ This issue is not reproducible with XCode 15.0.1 or higher.
 | 2.7.8 | Linux, macOS
 | 3.0.7 | Linux, macOS
 | 3.1.6 | Linux, macOS, Windows
-| 3.2.{4,5} | Linux, macOS, Windows
-| 3.3.{3,4,5} | Linux, macOS, Windows
+| 3.2.{4,5,6} | Linux, macOS, Windows
+| 3.3.{3,4,5,6} | Linux, macOS, Windows
+| 3.4.1 | Linux, macOS, Windows
 
 |===
 
@@ -302,9 +311,6 @@ Removes Tebako Ruby artifacts.
 `hash`::
 Calculates the Tebako script hash for use as a cache key in CI/CD environments.
 
-`extract`::
-Extracts the filesystem from a Tebako package.
-
 `version`::
 Displays the Tebako version.
 
@@ -595,24 +601,46 @@ brew bundle
 
 Tebako requires Bison 3+.
 
-On macOS 14, the default Bison version is 2.3, and the Homebrew formula is keg-only,
-which means that the full path to the Bison binary must be used to utilize the
-correct version.
+On macOS 14, the default Bison version is 2.3, and the Homebrew formula is
+keg-only, which means that the full path to the Bison binary must be used to
+utilize the correct version.
 
 Run the following command prior to using Tebako, or add it into your shell
 profile.
 
-====== jemalloc Library Build
+[source,sh]
+----
+export PATH="$(brew --prefix bison)/bin:$PATH"
+----
+
+====== jemalloc library build
+
+On macOS, the `libdwarfs` build script creates an additional `jemalloc`
+installation. This is done to satisfy the magic applied by folly during linking
+but uses a static library.
+
+If the `jemalloc` library 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 and therefore defines them wrongly (`lg-vaddr` parameter).
 
-The `libdwarfs` build script creates an additional jemalloc installation on macOS. This is done to satisfy the magic applied by folly during linking but uses a static library.
-If the library is created in an emulated environment (QEMU, Rosetta, etc.), there are known issues (link:https://github.com/jemalloc/jemalloc/issues/1997[jemalloc issue #1997]) where jemalloc incorrectly defines the number of significant virtual address bits (lg-vaddr parameter).
+Technically, these issues can be fixed by explicitly setting the
+`--with-lg-vaddr` parameter for the `jemalloc` build. However, we decided not to
+automate this since we do not feel that we can provide reasonable test coverage.
 
-These issues can be fixed by explicitly setting the `--with-lg-vaddr` parameter for the jemalloc build. We decided not to automate this since we do not feel that we can provide reasonable test coverage. Instead, our build script accepts the `LG_VADDR` environment variable and passes it to the jemalloc build as `--with-lg-vaddr=${LG_VADDR}`.
+Instead, our build script accepts the `LG_VADDR` environment variable and passes
+it to the jemalloc build as `--with-lg-vaddr=${LG_VADDR}`.
 
-The `LG_VADDR` parameter specifies the number of significant virtual address bits, which can vary based on the CPU architecture and emulation status.
+The `LG_VADDR` parameter specifies the number of significant virtual address
+bits, which can vary based on the CPU architecture and emulation status.
 
-Simple script to set `LG_VADDR`. Please note that it is provided for illustration only.
+This is a simple example script to set `LG_VADDR`.
 
+NOTE: This is provided for illustration only.
+
+[example]
+====
 [source,sh]
 ----
 #!/bin/bash
@@ -634,13 +662,9 @@ fi
 
 echo "Setting lg-vaddr to $LG_VADDR"
 ----
+====
 
 
-[source,sh]
-----
-export PATH="$(brew --prefix bison)/bin:$PATH"
-----
-
 ===== Windows
 
 ====== General
@@ -676,6 +700,7 @@ $ pacman -S git tar bison flex toolchain make cmake
 
 == Packaging
 
+[[root-folder-selection]]
 === Tebako root folder (aka prefix) selection
 
 The Tebako prefix determines the base directory for the Tebako setup.
@@ -726,7 +751,7 @@ the packaging environment and collects the required dependencies. Subsequent
 invocations are much faster.
 ====
 
-Upon the next invocation tebako will use previously created packaging
+Upon the next invocation, Tebako will use previously created packaging
 environment. The press process itself takes minutes.
 
 You can manage setup of packaging environment manually; please refer to
@@ -744,53 +769,100 @@ tebako press \
   [-c|--cwd=<package current working directory>]
   [-D|--devmode] \
   [-P|--patchelf] \
+  [-m|--mode=<bundle|both|application|runtime>] \
+  [-u|--ref=<runtime-reference>] \
   [-t|--tebafile=<path-to-tebafile>]
 ----
 
 Where:
 
 `<tebako-root-folder>`::
-the Tebako root folder (see details in the Tebako Root Folder Selection section)
+the Tebako root folder (see details: <<root-folder-selection>>)
 
 `Ruby`::
 this parameter defines Ruby version that will be packaged (optional, defaults to
-`3.1.6`)
+`3.2.6`)
 
 `project-root`::
-a folder at the host source file system where project files are located
+a folder at the host source file system where project files are located.
+This parameter is not required if the operation mode is `runtime`.
 
 `entry-point`::
 an executable file (binary executable or script) that shall be started when
-packaged file is called
+packaged file is called. This parameter is not required if the operation mode is `runtime`.
 
 `output`::
-the output file name (optional, defaults to `<current folder>/<entry point base name>`)
+(optional)
+the output file name.
++
+Defaults to `<current folder>/<entry point base name>`.
++
+On Windows output file will have `exe` extension.
+If the application is to be a separate file (`both` or `application` mode), it
+will have the same name with the `.tebako` extension.
 
 `log-level`::
 logging level for the Tebako built-in memory filesystem driver
 (optional, defaults to `error`)
 
 `cwd`::
+(optional)
 a folder within Tebako memfs where the packaged application will start. This folder should be specified relative to the memfs root.
-If not provided, the application will start within the current folder of the host (i.e., at $PWD).
-This option is required because it is not possible to change the directory to a memfs folder until the package is started, as opposed to any host folder
-that can be set as the current directory before Tebako package invocation.  Tebako saves original working directory in a global Ruby variable `$tebako_original_pwd`.
++
+If not provided, the application will start within the current folder of the
+host (i.e., at `$PWD`).
++
+This argument is required because it is not possible to change the directory to
+a memfs folder until the package is started, as opposed to any host folder that
+can be set as the current directory before Tebako package invocation.  Tebako
+saves the original working directory in a global Ruby variable
+`$tebako_original_pwd`.
 
 `devmode`:: flag that activates development mode, in which Tebako's cache and
 packaging consistency checks are relaxed.
 
 `patchelf`::
-flag that removal a reference to GLIBC_PRIVATE version of libpthread from tebako package. This allows Linux Gnu packages to run against versions of
-libpthread that differ from the version used for packaging. For example, package created at Ubuntu 20 system can be used on Ubuntu 22. This option makes
-sense and works on Gnu Linux only. The feature is exeprimental, we may consider other approach in the future.
+Allows forward-compatibility of Tebako packages with Linux GNU distributions.
++
+Specifically, this is a flag that removes a reference to the `GLIBC_PRIVATE`
+version of `libpthread` from a Tebako package.  This allows Linux GNU packages
+to run against versions of `libpthread` that differ from the version used for
+packaging.
++
+NOTE: This option only works on GNU Linux only.
++
+[example]
+For example, a package created at Ubuntu 20 system can be used on Ubuntu 22.
++
+NOTE: The feature is exeprimental, we may consider another approach in the future.
+
+`mode`::
+output mode for tebako package (optional, defaults to `bundle`).
+
+`bundle`::: place runtime and application to a single file
+`both`::: create both run-rime and application
+`application`::: create appplication only
+`runtime`::: create runtime only
+
+`ref`::
+(optional)
+Defaults to `tebako-runtime`.
+When a Tebako application package is created on Windows, it is linked against a
+Tebako runtime file name. The `ref` parameter allows to specify the name of the
+runtime file.
++
+NOTE: The `ref` option specificies the name of the runtime -- the runtime file
+can be recreated or changed but not renamed.
 
 `tebafile`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
-Please refer to the separate section below for tebafile description.
+Please refer to the separate section below for description of the tebafile.
 +
-NOTES:
-  * Development mode is *not intended for production use* and should only be used during development.
-  * `entry-point` and `project-root-folder` are required parameters and may be provided either via command-line or in `tebafile`.
+NOTE: Development mode is *not intended for production use* and should only be
+used during development.
++
+NOTE: `entry-point` and `project-root-folder` are required parameters and may be
+provided either via command-line or in the tebafile.
 
 [example]
 ====
@@ -831,9 +903,9 @@ $ tebako setup \
 
 Where:
 
-`<tebako-root-folder>`:: the Tebako root folder (see details in the Tebako Root Folder Selection section)
+`<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
 
-`Ruby`:: parameter defines Ruby version that will be packaged (optional, defaults to 3.1.6)
+`Ruby`:: parameter defines Ruby version that will be packaged (optional, defaults to `3.2.6`)
 
 `tebafile`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
@@ -858,7 +930,7 @@ $ tebako clean \
 
 Where:
 
-`<tebako-root-folder>`:: the Tebako root folder (see details in the Tebako Root Folder Selection section)
+`<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
 
 `tebafile`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
@@ -925,8 +997,14 @@ $ tebako hash
 
 === Tebako configuration file
 
-It is possible to provide all or some options for the `tebako setup/press/clean/clean_ruby` commands via Tebako configuration file ('tebafile').
-Tebafile is a YAML file with a single section 'options'. The options are the same as long names for the command line. For, example for the prefix option
+It is possible to provide all or some options for the `tebako
+{setup | press | clean | clean_ruby}` commands via a Tebako configuration file
+('tebafile').
+
+Tebafile is a YAML file with a single key `options`. The options are the same as
+long names for the command line.
+
+For example, for the prefix option:
 
 [source]
 ----
@@ -934,15 +1012,37 @@ Tebafile is a YAML file with a single section 'options'. The options are the sam
 ----
 the key in the YAML file would be 'prefix'.
 
-Below is an example tebafile that sets values for prefix and Ruby options
+.Example tebafile that sets values for prefix and Ruby options
+[example]
+====
+This is an example tebafile that sets values for prefix and Ruby options:
+
 [source,yaml]
 ----
 options:
   prefix: /tmp/tebako
   Ruby: 3.2.4
 ----
+====
+
+=== Options prefernce order
+
+Tebako supports several methods to set options. The table below show preference order and limitations for specific options.
+samller order means higher proirity.
+
+[cols="4", options="header"]
+|===
+| Order | Mode | Option source | Applicability
+
+| 1 | All | Command-line | All options
+| 2 | All |Tebako configuration file | All option except ``--tebafile`` (you can not specify new tebafile in a tebafile)
+.2+| 3 .2+| All .2+| Environment variable | TEBAKO_PREFIX to set ``--prefix`` option
+| LG_VADDR to set ``--with-lg-vaddr`` jemalloc parameter
+.2+| 4 | ``runtime`` | Tebako defaults | All options except ``--entry-point`` and ``--root`` that are mandatory
+| ``bundle``, ``both``, ``application`` | Tebako defaults | All options
+
+|===
 
-Please note that the options provided on the command line have preference over tebafile settings.
 
 === Exit codes
 
@@ -1063,7 +1163,9 @@ These scenarios determine how the project is packaged and where the entry point
 
 == Run-time options
 
-Generally Tebako package passes command line options to the packaged application
+=== General
+
+Generally Tebako package passes command line options to the packaged application.
 
 [example]
 ====
@@ -1091,9 +1193,53 @@ myproject --option --parameter value
 ----
 ====
 
-However there are several command-line parameters that are intercepted processed by Tebako bootstrap code as follows
+However there are several command-line parameters that are intercepted processed
+by Tebako bootstrap code as described below.
+
+=== Running tebako image by tebako runtime (`--tebako-run` option)
+
+Tebako provides an option to an extract its DwarFS filesystem from a package to
+a local folder for verification or execution.
+
+[source,sh]
+----
+$ <tebako-runtime> --tebako-run [<tebako application>]
+----
+
+Where,
+
+`<tebako runtime>`::
+The tebako runtime in ```runtime``` or ```both``` mode
+
+`<tebako application>`::
+The tebako application package created in ```application``` or ```both``` mode
+
+[example]
+====
+Creating separate runtime and application and running it:
+
+[source,sh]
+----
+tebako press -m runtime -o tebako-runtime
+tebako press -m application -o tebako-application -e hello.rb -r test
+tabako-runtime --tebako-run tebako-application Maxim
+----
+where hello.rb is the Ruby application
+[source,Ruby]
+----
+# frozen_string_literal: true
+
+puts "Hello, #{ARGV[0]}!"
+----
+And expected output from ```tabako-runtime --tebako-run tebako-application Maxim``` is
+[source,sh]
+----
+Hello, Maxim!
+----
+
+====
 
-=== Image extraction (--tebako-extract option)
+=== Image extraction (`--tebako-extract` option)
 
 Tebako provides an option to an extract its DwarFS filesystem from a package to
 a local folder for verification or execution.
@@ -1126,27 +1272,42 @@ require 'fileutils'
 FileUtils.copy_entry '<in-memory filesystem root>', ARGV[2] || 'source_filesystem'
 ----
 
-=== Mounting Host Folder to Tebako Memfs (`--tebako-mount` option)
+=== Mounting host folder to Tebako memfs (`--tebako-mount` option)
+
+Some programs unconditionally use folders located under the application root,
+and when processed by Tebako or similar tools, these folders are included in the
+packaging.
+
+[example]
+====
+Rails, for example, does not provide a configuration option to change where
+it expects the `tmp` folder to be.
+
+The location is hardcoded in multiple places within the Rails codebase, residing
+under the application root, and as a result, it gets included in the read-only
+Tebako memfs.
 
-Some programs unconditionally use folders located under the application root, and when processed by Tebako
-or similar tools, these folders are included in the packaging.
+Although patches have been proposed (e.g.,
+https://github.com/rails/rails/issues/39583), there is currently no way to
+change the paths for temporary files, caches, and sockets.
+====
 
-For example, there is no configuration option to change where Rails expects the `tmp` folder to be.
-The location is hardcoded in multiple places within the Rails codebase, residing under the application root,
-and as a result, it gets included in the read-only Tebako memfs. Although patches have been proposed
-(e.g., https://github.com/rails/rails/issues/39583), there is currently no way to change the paths for
-temporary files, caches, and sockets.
+To address this inevitable limitation for Ruby applications,
+Tebako provides an option to mount a host folder to the memfs tree.
 
-To address this limitation in Rails and similar issues in other applications, Tebako provides an option
-to mount a host folder to the memfs tree.
+When using Tebako, consider the packaging scenario mentioned above, as it
+defines the layout of the application tree.
 
-When using Tebako, consider the packaging scenario mentioned above, as it defines the layout of the application
-tree. The `--tebako-extract` option may be useful for understanding the placement of files and folders.
+The `--tebako-extract` option may be useful for understanding the placement of
+files and folders.
 
 [example]
 ====
-The following command starts a `rails.tebako` package with `$PWD/tmp` mounted as `local/tmp` in the memfs.
+The following command starts a `rails.tebako` package with `$PWD/tmp` mounted as
+`local/tmp` in the memfs.
+
 Any remaining command-line parameters are passed to the application.
+
 [source,sh]
 ----
 rails.tebako --tebako-mount local/tmp:$PWD/tmp server
@@ -1154,15 +1315,17 @@ rails.tebako --tebako-mount local/tmp:$PWD/tmp server
 ====
 
 The `--tebako-mount` option has the following syntax:
+
 [source,sh]
 ----
 --tebako-mount <memfs path>:<host path>
 ----
 
-The `--tebako-mount` option can be repeated multiple times to mount more than one object. The `memfs path`
-is relative to the memfs root, and it is recommended to use absolute paths for host objects. Both directories
-and files can be mounted in this way. Tebako allows overlaying existing memfs objects, so there are no significant
-limitations.
+The `--tebako-mount` option can be repeated multiple times to mount more than
+one object. The `memfs path` is relative to the memfs root, and it is
+recommended to use absolute paths for host objects. Both directories and files
+can be mounted in this way. Tebako allows overlaying existing memfs objects, so
+there are no significant limitations.
 
 == Trivia: origin of name
 

data/common.env

@@ -1,5 +1,5 @@
 BUILD_TYPE=Release
 DEPS=deps
 INCBIN_TAG=348e36b
-DWARFS_WR_TAG=v0.8.3
-RUBY_VER=3.2.5
+DWARFS_WR_TAG=v0.9.2
+RUBY_VER=3.2.6

data/include/tebako/tebako-prism.h

@@ -0,0 +1,51 @@
+#include <fcntl.h>
+
+static pm_string_init_result_t
+tebako_string_file_init(pm_string_t *string, const char *filepath) {
+
+    // Open the file for reading
+    int fd = open(filepath, O_RDONLY);
+    if (fd == -1) {
+        return PM_STRING_INIT_ERROR_GENERIC;
+    }
+
+    // Stat the file to get the file size
+    struct stat sb;
+    if (fstat(fd, &sb) == -1) {
+        close(fd);
+        return PM_STRING_INIT_ERROR_GENERIC;
+    }
+
+    // Ensure it is a file and not a directory
+    if (S_ISDIR(sb.st_mode)) {
+        close(fd);
+        return PM_STRING_INIT_ERROR_DIRECTORY;
+    }
+
+    // Check the size to see if it's empty
+    size_t size = (size_t) sb.st_size;
+    if (size == 0) {
+        close(fd);
+        const uint8_t source[] = "";
+        *string = (pm_string_t) { .type = PM_STRING_CONSTANT, .source = source, .length = 0 };
+        return PM_STRING_INIT_SUCCESS;
+    }
+
+    size_t length = (size_t) size;
+    uint8_t *source = xmalloc(length);
+    if (source == NULL) {
+        close(fd);
+        return PM_STRING_INIT_ERROR_GENERIC;
+    }
+
+    long bytes_read = (long) read(fd, source, length);
+    close(fd);
+
+    if (bytes_read == -1) {
+        xfree(source);
+        return PM_STRING_INIT_ERROR_GENERIC;
+    }
+
+    *string = (pm_string_t) { .type = PM_STRING_OWNED, .source = source, .length = length };
+    return PM_STRING_INIT_SUCCESS;
+}