Build Argentum From Sources on Windows

Argentum uses vcpkg that automatically installs and builds all dependencies for all platforms in all configurations. Argentum dependencies include LLVM, Skia, SDL and other libraries.

The initial build takes ≈60Gb of storage, it requires 16+Gb RAM, and depending on device configuration can take up to 6 Hours.

All subsequent rebuilds take minutes.

Install prerequisites

• CMake (newest stable) from https://cmake.org/download/
• Visual studio (community is ok) https://visualstudio.microsoft.com/downloads/
  this also installs Windows Kit and Ninja build system
• Git: https://www.git-scm.com/download/win

Install vcpkg

Go by this instruction: https://learn.microsoft.com/.../vcpkg/get_started

I believe it's better to install vcpkg system-wide because it stores lots of data inside its directory (in the Argentum case it's about 40Gb). I believe you'd prefer having just a single instance of this monstrosity, not one per project. Let's put it at c:\vcpkg (or wherever you want):

cd /d c:\
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg && bootstrap-vcpkg.bat
set VCPKG_ROOT="C:\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

You may also want to put all these environment variables to your user profile using the Windows System Environment Variables panel (This PC->Properties->Advanced System Settings->Environment Variables). This would save you from setting them each time you start cmd

Get Argentum sources

We need a directory on a drive having at least 15Gb of free space. Let it be c:\pojects\argentum

cd /d c:\projects
git clone https://github.com/karol11/argentum.git

First Build (Release)

• It will take hours.
• File vcvars64.bat is a part of Visual Studio installation,
  It sets environment variables to make the cmake find the build tools and platform libraries.
  It might reside in a different location, just search for it.
• cmake --preset default -DCMAKE_BUILD_TYPE=Release actually downloads all dependencies and build them (both in debug and release) it's the longest part of all process. Also it prepares build of the Argentum itself in release mode.
• cmake --build build performs the actual build of Argentum. It needs vcvars64.bat to work.

cd /d c:\projects\argentum
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"
cmake --preset default -DCMAKE_BUILD_TYPE=Release
cmake --build build

Inspect the Build Results

Build results are organized in the output directory:

• output/bin: contains the agc compiler and batch files that help to compile-link-run the argentum apps in demo mode and from VSCode
• output/apps: is a place for all compiled argentum demo apps, obj-files and DLLs used by binding modules - sdl, curl, sqlite - everything that's needed to run argentum demo apps
• output/libs: holds the argentum runtime library, bindings and DLLs import libraries
• output/licenses: license files for all dependencies
• output/workdir: resources for demo apps,
• output/ag: contains the sources for argentum modules and demo apps.

Run the Argentum Demo Apps

output\runme.bat

This batch file:

• Outputs each demo app source code (from output/ag/*) to console
• Compiles it using (output/bin/agc.exe) to an obj-file (in output/apps)
• Links it (using Visual Studio cl.exe) with argentum runtime libraries, bindings and import libraries (from output/libs/)
• Puts the resulting exe into output/apps/ along with all DLLs needed by sdl/curl/sqlite.
• And executes it with *workdir* as a current directory.

Alternatively you can build and run any ag-application existing in the ag directory:

output\bin\run-release.bat sceneDemo

After the sceneDemo is build, it can be executed directly:

cd workdir
..\apps\sceneDemo.exe

You can copy this 46Kb executable along with needed SDL DLLs and image files from the workdir to make a portable executable or wrap it in the installer. This application needs no VM, Framework or runtime environment to run.

Create a standalone Argentum demo release

In the previous section we built Argentum demo apps using the Microsoft Visual Studio linker and C-runtime library. In this section we are going to make the minimal demo Argentum compiler working without Visual Studio.

Let's switch to the LLVM linker:

1. Download and extract previous Argentum demo: https://github.com/.../argentum-demo.7z
2. Copy linker argentum-demo\bin\lld-link.exe to output\bin
3. Copy standalone subset of runtime libs from argentum-demo\libs to output\libs (please don't overwrite your newer files with downloaded older ones).
4. Profit (the run-release.bat automatically checks for and starts using llvm linker and libs).

Now the whole output directory becomes a portable Argentum demo.
But you will probably want to delete parts that are not necessary for demo:

• output/debug - contains debug versions of dlls libs and compiler
• output/apps/*.exe *.obj - are leftovers of previous launches of runme.bat or run-release.bat

Debug Argentum apps

1. Build the Argentum application (let's use graph for example) with debug info: output\bin\build-debug.bat graph
2. Launch Ms VisualStudio
3. File->Open project
4. Select output\apps\graph.exe
5. Debug->StepInto (or F11)

This allows to traverse argentum source code (step in/out/over), set break points, run-to.

It also allows to view threads, trace stacks and (very limited) inspect variables.

This way allows to debug Argentum code, but not to step in the C/C++ FFI functions and functions of the Argentum runtime library.

Debug Argentum apps + FFI

Preparation steps

Build a debug version of Argentum:

cmake --preset default -DCMAKE_BUILD_TYPE=Debug
cmake --build build

This creates three more directories inside the output\debug:

• output/debug/bin - Debug version of the Argentum compiler (you will probably never need it, unless you want to debug the compiler itself)
• output/debug/apps - Placeholder for debug versions of all DLLs, empty b/c they are almost never needed.
• output/debug/libs - Debug versions of ag-runtime library, all existing bindings and all import libraries.

To debug any app with stepping in Ag-runtime and C-FFI functions you need to repeat the same steps as above but instead of using output\bin\build-debug.bat you need to run output\bin\build-debug-ffi.bat that links the ag-application to debug/libs.

With this changes you'll be able to step in all runtime functions and FFI-bindings.

TBD:

• integrate with VSCode,
• add new demo ag-modules,
• add new bindings,
• build on other platforms and arch.