Examples and Tips & Tricks

[ProfessorManhattan]

Hey, I love this product but I feel like I'm not utilizing it to its fullest. I have run into the problem where I want to include a binary in a build so I use something like --include-path /usr/bin/jq. However, it fails to run after compiling because jq requires extra libs. I find those libs out by running ldd /usr/bin/jq but its a very tedious process for something that could probably be automated.

I am also unsure of the difference between --include-path, --include-bin, --include-bin-file, --preserve-path, and --preserve-path-file. Can I use any of these options to automatically detect the shared libs that a binary relies on?

Anyway, my final ask is for a set of examples that illustrate which commands I should be using any why. Thank you!

[kcq]

The --include-bin and --include-exe should be useful with jq.

The --include-bin /usr/bin/jq param should include /usr/bin/jq and its binary dependencies (the shared objects jq imports), so you wouldn't need to explicitly add those by hand.

The --include-exe jq param is similar to --include-bin, but it also allows you to specify just the executable name. When you do that it'll find the executable in one of the PATH locations in your container image.

Good idea to have an extra set of examples for these flags!

[kcq]

converting this issue to discussion...

[rlia]

How can I use --include-path and --preserve-path differently?
I do not even know why there is more than one of these.

--include-path
--include-path-file
--include-bin
--include-bin-file
--include-exe
--include-exe-file

Any tips for understanding it other than reading the source code? Thank you.

[kcq]

The --preserve-path flag ensures that the target file is a part of the optimized image in its original state. This is useful when your app has a data file that gets updated when your application runs, but you want the original version of the file in the minified image. This is relevant because Slim runs the target container image and it extracts the files for the minified image from that running container, so some of the extracted files might be mutated. If you want the original version of the extracted file you use --preserve-path and if it doesn't matter or if the target file isn't mutated (most files) then you use --include-path.

The post earlier in the thread give an overview of the differences between *-path, *-bin and *-exe flags. Note how using *-bin and *-exe is different using the examples above: --include-bin /usr/bin/jq vs --include-exe jq. Note the *-exe version doesn't require a full path for jq. This is because Slim looks at all configured PATH locations in the container to find the jq executable. This behavior is only possible for executables. The binary objects (aka shared objects) can be in many different locations and that's why you need to specify the full path to them.

The binary objects (and executables) import dynamically loaded libraries (which are also binary objects themselves), so simply including the binary object file is not enough. You also need to included the imported dynamic libraries for those binary objects to work. This is what --include-bin (and --include-exe) allow you to do. You point at a binary file (could be an executable or a shared library) and Slim will discover all of its dynamically loaded dependencies and it will automatically keep those additional files too along with the target binary file you point to.

One thing to note here... Slim finds the statically linked dynamically loaded dependencies. This is the most common type of dynamically loaded dependencies. The Libc shared library is the best example of it. However, some apps have plugins implemented using on-demand shared object loading where the app calls the 'load library' function explicitly. These dynamically loaded libraries won't be automatically detected. The most common solution for this is to explicitly 'include' these plugins with the --include-bin flag.