Namespaces

Overview

A namespace is a group of Viash components.

Here are some benefits of grouping your components:

• Grouping components in namespaces allows for categorizing components.
• Each teams of developers can work on a different set of components in parallel, which improves the separation of concerns.
• Generating build targets and unit testing can be done in bulk, with optional filtering by namespace using the viash ns commands.

This guide will cover how to define a namespace and use it with Viash.

Adding components to a namespace

There are two ways of defining a namespace: either by adding the namespace property to the Viash config file or by creating a directory structure. You can use one or both of these methods in your projects.

Namespace property

You can assign a component to a namespace by defining its namespace attribute in the viash config file:

functionality:
  name: some_component
  namespace: my_namespace

Directory structure

Viash can deduce namespaces automatically if you structure the components hierarchically. The namespace directories should be in the root of your (source) directory, with the component directories inside, grouped per namespace.
In the example below, there are two namespaces: namespace_one and namespace_two, each of these namespaces has one or more components assigned to them:

src
├── namespace_one
│   ├── component_one
│   │   ├── config.vsh.yaml
│   │   └── script.sh
│   └── component_two
│       ├── config.vsh.yaml
│       └── script.sh
└── namespace_two
    └── component_three
        ├── config.vsh.yaml
        └── script.sh

Here, namespace_one groups component_one and component_two together while namespace_two only consists of a single component, component_three.

Using the viash ns subcommands

Viash comes with a useful viash ns command to work with namespaces. This can be used to inspect, test and build the components that are part of a namespace.
We’ve provided a simple example project if you wish to test these commands. Its components use bash for some integer and string manipulation.

Download namespace_example.zip

Listing components and namespaces

The viash ns list command is the namespace equivalent of viash config view, it outputs a parsed version of all config files found in a directory and their subdirectories:

viash ns list -src src

This prints all fields to the terminal, even those not defined in the config files themselves. Here’s a part of the output:

Output

- functionality:
    name: "replace"
    namespace: "string_manipulation"
    authors: []
    inputs: []
    outputs: []
    arguments:
    - type: "string"
      name: "--text"
      alternatives: []
      example: []
      default:
      - "Hello world!"
      required: false
      values: []
      direction: "input"
      multiple: false
      multiple_sep: ":"
    - type: "string"
      name: "--search"
      alternatives: []
      example: []
      default:
      - "Hello"
      required: false
      values: []
      direction: "input"
      multiple: false
      multiple_sep: ":"
    - type: "string"
      name: "--replace"
      alternatives: []
      example: []
      default:
      - "Greetings"
      required: false
      values: []
      direction: "input"
      multiple: false
      multiple_sep: ":"
    resources:
    - type: "bash_script"
      path: "script.sh"
      is_executable: true
      parent: "file:/.namespace_example/src/string_manipulation/replace/config.vsh.yaml"
    description: "Search for a substring in a string and replace it with another string"
    test_resources:
    - type: "bash_script"
      path: "test.sh"
      is_executable: true
      parent: "file:/.namespace_example/src/string_manipulation/replace/config.vsh.yaml"
    info: {}
    dummy_arguments: []
    set_wd_to_resources_dir: false
  platform:
    type: "native"
    id: "native"
  platforms:
  - type: "native"
    id: "native"
  info:
    config: "namespace_example/src/string_manipulation/replace/config.vsh.yaml"
    platform: "native"
    viash_version: "0.5.12"
    git_commit: "d9d624de0264b1154d7eeb5dba3c1deb567311ac"
    git_remote: "https://github.com/..."
...

Unit testing a namespace

You can test multiple components using the viash ns test command.

viash ns test --src src

Tip

To speed up the testing, you can use the parallel flag to test all components at once:

viash ns test --src src --parallel

This will test each component in series and will output a tab separated output that contains the results:

The working directory for the namespace tests is /tmp/viash_ns_test2526740097581645786
           namespace        functionality             platform            test_name exit_code duration               result
 string_manipulation              replace               native                start                                        
 string_manipulation              replace               native              test.sh         0        0              SUCCESS
                math             subtract               native                start                                        
                math             subtract               native              test.sh         0        0              SUCCESS
                math                  add               native                start                                        
                math                  add               native              test.sh         0        0              SUCCESS

Building a namespace

Multiple components can be build in series using the viash ns build command:

viash ns build --src src --target target

Tip

To speed up the building, you can use the parallel flag to build all components at once:

viash ns build --src src --target target --parallel

This will output the following to the console:

Exporting replace (string_manipulation) =native=> target/native/string_manipulation/replace
Exporting subtract (math) =native=> target/native/math/subtract
Exporting add (math) =native=> target/native/math/add

An executable and/or module will be generated for every target platform defined in each of the component configs. These are grouped per platform and namespace in the target directory:

target
└── native
    ├── math
    │   ├── add
    │   │   └── add
    │   └── subtract
    │       └── subtract
    └── string_manipulation
        └── replace
            └── replace