1 Dependencies
Kumori DSL supports dependency management through a module system that allows you to import and use external packages in your projects. This guide covers how to manage dependencies effectively.
Every kdsl project starts with a kumori.mod.json file. The kdsl mod init command is used to create this essential manifest file at the root of your project directory. It requires you to specify the unique module path for your project.
This command will create a kumori.mod.json file with content similar to this:
The module field defines its unique identifier. The requires array is initially empty, as your newly initialized module does not yet have any external dependencies.
Every module that has dependencies will make use of a local cache, which is essentially a directory within your module that holds the actual dependencies needed for your module. It is possible to specify a custom path for your dependencies by simply adding a second argument to the kdsl mod init command:
This command will create a kumori.mod.json file with content similar to this:
Now, all your dependencies will be downloaded to that location. If not specified, this location defaults to ".kumori/mod" within your module.
You can specify a path within the current module (i.e. “.custom/location”, “dependencies/”) or you could also use a full absolute path to store the dependencies anywhere in your filesystem (i.e. “/home/YourUser/Documents/mycache”).
1.1 Adding dependencies
Dependencies are specified in the requires array within the kumori.mod.json file. This file is not meant to be updated manually. Instead, you should use the kdsl mod dep command to add, update or remove dependencies.
1.2 Aliasable dependencies
When adding dependencies to your module, you have the option to assign an alias to each dependency. This is particularly useful when you want to avoid naming conflicts or when you want to refer to a dependency with a different name in your code.
Assume the following aliased dependency in your kumori.mod.json file:
In this example, the module kumori.systems/component is aliased as my.component. When you want to import and use this dependency in your Kumori DSL, you would do so using the alias like this:
1.3 Local dependencies
You can add local dependencies to your module by specifying the absolute path to the module in the requires array of your kumori.mod.json file.
Assume the following directory structure:
/absolute/path/to/local/module
└── component
└── component.h.kumori
└── component.kumori
└── example
└── service
└── service.h.kumori
└── service.kumori
└── deployment.kumori
└── kumori.mod.json
└── kumori.mod.jsonInside the example folder (which is a separate module) you can reference the local module by adding it to the requires array in its kumori.mod.json file like this:
Then, in your service.kumori file inside the example folder, you can import and use the local module like this:
It is recommended to use an alias when adding local dependencies to avoid potential conflicts with other modules that might have the same name and to improve clarity when importing them in your code.
1.4 The .vendor directory
Along with the cache location, where all the dependencies are downloaded, you can place additional dependencies directly into a .vendor directory located at the root of your module. Any module placed in this directory will be used as a dependency without needing to download it from a remote registry.
This is particularly useful for local development or when you want to include a dependency that is not available in any remote registry.
1.5 Registries
Registries offer powerful ways to manage and distribute your modules. For more information on how registries work and how to configure them, please refer to the Registries guide.
1.6 Module metadata for publishing
When you are ready to publish your module to a registry, you might want to publish it some of its artifacts to your module index file, to be able to use registries or to publish your module into the Axebow Marketplace. For that, you can create a _index.json file at the root of your module, which contains metadata about your module.
When placed at the root of your module, the kdsl will automatically pick up this file when you run the kdsl index create command to generate the index entry for your module.
This file follows a specific structure. Esentially, it contains some information about the module, a defaults section to define default values for various fields and a collection of artifacts, each one with its own metadata that will later fill the index entry for your module.
The following is an example of a _index.json file:
{
"location": "https://github.com/your-org/your-module.git",
"defaults": {
"requirements": {
"cpu": 1,
"memory": 1
},
"marketplace": true,
"categories": [],
"tags": []
},
"artifacts": [
{
"type": "service",
"name": "MyService",
"location": "services/myservice",
"description": "A sample service that does X",
"requirements": {
"cpu": 0.5,
"memory": 2
},
"icon": "services/myservice/icon.png",
"categories": ["utility", "network"],
"tags": ["http", "api", "rest"]
},
{
"type": "component",
"name": "MyComponent",
"location": "components/mycomponent",
"description": "A sample component that does Y",
"marketplace": false
}
]
}