Building Your Application

This section focuses on building Atym containers from your C/C++ application code. The build process transforms your application into a deployable Atym container that can run on compatible devices. While the Quickstart Guide offers a brief introduction to building containers, this Developer Guide provides a comprehensive understanding of the build process and its underlying mechanisms.

---

Building the Container

In this section, we'll walk through the process of building an Atym container from your C/C++ application code.

Suggestion

Feel free to use one of our samples from the Atym Toolchain repo to follow a long if you've not yet created a new project.

1. Navigate to Your Project Directory

First, navigate to your project directory.

cd your-project/

2. Build the WASM Module

Create a build directory and compile the application to WebAssembly:

mkdir build && cd build
cmake ..
make

If the build is successful, you should see output similar to this:

[ 50%] Building C object CMakeFiles/your-project.wasm.dir/main.c.obj
[100%] Linking C executable your-project.wasm
[100%] Built target your-project.wasm

The generated WASM module will be named after the APPNAME variable defined in your CMakeLists.txt file.

For example, if your CMakeLists.txt contains:

set(APPNAME your-project)

Then the output will be your-project.wasm inside the build directory. This module is used by the atym build command in the next step.

Testing Your WASM Module (Optional)

You can test your compiled WASM module locally using iwasm before proceeding to container creation:

iwasm your-project.wasm

Note

This local testing works for applications that use standard C library functions (libc). However, applications that use Atym-specific APIs will not run properly with iwasm and should be tested on the Atym runtime.

iwasm is included by default in the Atym dev container as described in the Development Environment Setup page.

3. Create the Container

Return to the project root directory and build the Atym container with the atym build command:

cd ..
atym build

By default, atym build will look for build.yaml in the top-level of your project to understand how to build your container. However, you can provide a different image definition file by simply supplying the -f option like so:

atym build -f my_build.yaml 

4. Verify the Container was Created

When you run the atym build command, you'll see detailed output of the build process:

Parsing buildfile:  build.yaml
Building from current Directory...
Building container image start...
Validate image definition file...
Creating Container Directory...
Creating OCI image layout...
Creating image index...
Creating image manifest...
Add layers to image manifest...
Computing hash for WASM module...
Create WASM module layer...
Creating zip file...
Image create complete.
Image build directory can be found at:  /home/demo_user/.atym/your-project

The last line confirms where your container image is stored. If the build is successful, you'll find a new .atym folder in your home directory. Inside, a subdirectory will match the container image name defined in your build.yaml file.

If your container image is named your-project, the directory structure will be:

~/.atym/your-project/
├── blobs
├── index.json
└── oci-layout

This directory contains all the container's contents, including blobs, index.json, and oci-layout, which are essential for storing and managing the image.

Learn More

If you'd like to learn more about how container images in Atym are constructed, check out the Image Components page.

---

Understanding the Build Process

In summation, the Atym build process transforms your compiled WebAssembly module into a fully functional container that can be deployed to Atym-enabled devices. This process includes:

1. WASM module Creation: Your project is compiled to a WebAssembly module.
2. Container creation:: The atym build command uses your build.yaml configuration to generate the Atym container structure, sets your WebAssembly module as the primary executable, set up the runtime environment, and incorporate necessary metadata.
3. Result: The final output is an OCI-compliant container image stored locally in the ~/.atym directory. From here, you can push your container to Atym Hub, making it available for deployment to Atym-enabled devices.

---

Troubleshooting Common Issues

Below are common errors you might encounter when building Atym containers and their likely solutions:

Error Message	Possible Cause	Solution
Build Definition File Not Found: Error: buildfileName 'build.yaml' does not exist	Incorrect working directory when running the build command. OR, you have a non-standard named build definition file.	Navigate to your project root directory and ensure your build.yaml file is located there. This error commonly occurs when you're in the build directory instead of the project root. OR, if this issue is because you created your own build definition file, simply specify the file name via the -f flag like so atym build -f file_name.