New Argentum project structure

Argentum is a modular language. Modules:

• isolate names,
• define dependencies,
• define order of initialization and destruction of global immutable state,
• provide versioning (planned),
• allow partial separate compilation: parsing, name resolution and type checking stages (planned).

Module is always a single text source file. It starts with a series of using declaration that define dependencies on other modules with optional imports of class/function/constant names from those used modules.

Argentum SDK is a set of modules residing in a specific directory. There might exist multiple versions of SDK in the same host, so there is no global variable or standard directory name for one system-wide SDK.

Your application is also a module. You build it by calling agc compiler with these mandatory flags:

agc -src path/to/directory/with/all/modules -start yourAppModule -o outputObjFile.obj

Where src defines a path to a directory containing your application file and all modules including ones from SDK.

Performance-wise it's ok to put all modules in one directory. Compiler will access/read/parse only tree of used modules. It's also ok to put into a single module as many classes/functions as needed, because compiler will include into resulting compiled program only the used classes and functions.

Though this single directory-for-everything approach is ok for compilation efficiency and resulting executable size, it has its own disadvantages for project organization. Let's say, it works only for very basic scenarios - simple test applications. So a new multidirectory structure was introduced:

Multidirectory project (new)

Real life apps need to:

• Separate the application specific modules/libraries and application source code from SDK
• Retarget application builds between SDKs
• Create sub-SDKs - a company-specific or team-specific sets of modules, that aren't part of SDK but common for multiple projects.
• Create platform-specific overrides for some modules.

This is all feasible, using multiple -src parameters:

agc \
-src ./android/modules \
-src ./sdk/modules \
-src ${COMPAY_DIR}/lib \
-src ~/myApplication/src \
-start myApp -o outputObjFile.obj

There might be many -src parameters, defining a list of directories, and argentum compiler searches for the start module and all modules it directly or indirectly uses in this list.

Order matters. For example, If android/modules directory contains a module having the same name as SDK, compiler uses one from android/modules because it's listed first.

This list of source directories covers all scenarios listed above.

Refs

Sometimes it is needed to include a module into a specific directory virtually:

• if one module should reside in multiple libraries without copying it into multiple places
• if source ag-file defines FFI bindings and it's better to retain it in the same place as its C/C++ counterpart
• if a module needs to be accessible under different names for versioning or copyright purposes

Argentum compiler uses module name as a file name, adding ".ag" extension. If current directory does not contain "*.ag" file, compiler checks for an "*.ag-ref" file with the same name. This file, if exists, should contain a path to the real ag-file location. This allows to share modules between libraries or create virtual libraries containing modules from different places.

Readiness

More than one -src command line params and *.ag-ref "sym-links" are supported in argentum build from sources.

• It's already used to structure output/ag directory - separate library-SDK modules from "examples"
• "*.ag-ref" files allowed to move all FFI wrappers back to their C/C++ subprojects and referencing them from "ag-lib" directory.