Project file (.warproj / .warpcfg)

See also the guide: Project.

.warproj — @Project

@Generator (nested inside @Project)

@Paths (nested inside @Generator)

.warpcfg — @GeneratorConfig

Top-level keys (Date Format, Print Mode, Commitment, etc.), @Screen/@FunctionKeys, and the date/time/timestamp formats are unique at the project level: they aren’t repeated per profile.

@Profile (nested inside @GeneratorConfig)

A .warpcfg declares one or more deployment profiles (typically Dev, UAT, Prod, though the name is free-form) inside @GeneratorConfig. Each @Profile "Name" groups its own @Connection, @Deployment, and @License — so a single project can point to different servers/libraries/licenses depending on the environment, without maintaining several .warpcfg files.

@GeneratorConfig {
    @Profile "Dev" {
        @Connection { ... }
        @Deployment { ... }
    }
    @Profile "Prod" {
        @Connection { ... }
        @Deployment { ... }
        @License { ... }
    }
}

Declaring at least one @Profile is mandatory: @Connection/@Deployment/@License declared directly inside @GeneratorConfig (without wrapping them in @Profile) are no longer valid (error E00290). A @GeneratorConfig with no @Profile at all gives error E00291.

How the active profile is chosen for generate/build/reverse/license-status (the validate action ignores profiles):

1. The CLI’s --profile <Name> flag, case-insensitive.
2. If omitted, Default Profile from @Project (see the .warproj — @Project section above).
3. If there’s no Default Profile either but the .warpcfg only declares one @Profile, that one is used.
4. If none of the above applies and there are several profiles declared, the compiler fails with error E00293, listing the available profiles.

Requesting a profile that doesn’t exist (via --profile or Default Profile) fails with error E00292, also listing the available profiles.

@Screen (nested inside @GeneratorConfig)

@FunctionKeys (nested inside @Screen)

One F<n> : "Label" entry per line (n from 1 to 24, e.g. F3 : "Exit"). Attached to its own event with Event 'Name' <n> ... EndEvent in a Screen’s @Source.

@Connection (nested inside @Profile)

How to reach the IBM i:

ssh/sftp/ftp use native clients: there’s no need to have any ssh/scp/sftp/ftp client installed on the machine running the compiler.

Examples by protocol and authentication method

SSH or SFTP with a key (ssh/sftp are equivalent: the native client uses the same transport for both):

@Connection {
    Host        : MYHOST
    User        : MYUSER
    Auth Method : key
    Key File    : ~/.ssh/id_ed25519_ibmi
    Protocol    : ssh
    Port        : 22
    Timeout     : 30
}

SSH or SFTP with a password — the password isn’t written into the .warpcfg; it’s read from the WARPGATE_PASSWORD environment variable, which must exist before opening VSCode (or the terminal the compiler runs from):

@Connection {
    Host        : MYHOST
    User        : MYUSER
    Auth Method : password
    Protocol    : sftp
    Port        : 22
    Timeout     : 30
}

FTP with a password — FTP has no concept of key-based authentication (Auth Method: key with Protocol: ftp is a validation error), so it only accepts password/interactive, both read from the same WARPGATE_PASSWORD variable:

@Connection {
    Host        : MYHOST
    User        : MYUSER
    Auth Method : password
    Protocol    : ftp
    Port        : 21
    Timeout     : 30
}

Generating the Key File

Auth Method: key needs an SSH key pair: a private one (the one Key File points to) and a public one, which must be authorized on the IBM i user profile.

1. Generate the key pair (on the machine running the compiler/VSCode, not on the IBM i):

   ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_ibmi -N ""
   

   This creates id_ed25519_ibmi (private — the path that goes in Key File) and id_ed25519_ibmi.pub (public). -N "" leaves the key without a passphrase, a requirement for Auth Method: key.
2. Copy the contents of id_ed25519_ibmi.pub (a single line) to the end of the .ssh/authorized_keys file inside the IBM i user’s IFS home directory (e.g. /home/MYUSER/.ssh/authorized_keys) — create the file and directory if they don’t exist. The IBM i’s SSH daemon (SSHD, from product 5733-SC1) must be active and configured to accept key-based authentication.
3. Verify that Key File in @Connection points to the private key’s path on the local machine (not the .pub one), and that Auth Method is key.

@Deployment (nested inside @Profile)

Where/how to deploy and compile on the IBM i:

@License (nested inside @Profile)

Optional block with the licensing configuration, specific to each profile — so Dev/UAT/Prod can consume different licenses or licensing services. Keys are case-insensitive. See the Licensing guide.

@License {
    Host        : "servidor01.dominio.local"
    Port        : 7443
    Fingerprint : "3f2a9c41d87b05e6a1c4f0937be2d5688a1f4c0d29e7b3a65c8d1f0e4b7a9c23"
}

Full example

See Project: .warproj and .warpcfg for a complete example with both files.