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)

The compiler does not warn if the chosen row overlaps the @Layout: whoever moves it must leave that row free. If the keys do not fit in one line and there is no F24 rotation, the second line goes up from the chosen row.

@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.

Key rotation with F24. If F24 is declared here (e.g. F24 : "More keys") and no Event in the file claims it (Event 'X' 24), the Screen’s attention line can rotate. All keys are considered (those in @FunctionKeys plus those of Events with a key). If they fit in one line, there is no rotation and the line is generated as usual. Otherwise they are split into sets ordered by key number, each fitting in a single line and ending with F24=<label>. Pressing F24 shows the next set (after the last one it returns to the first); the keypress only changes the key line and does not run any event. The usable width is the screen width minus 2 columns (the window width in a popup). Without F24 declared, or with an Event on F24, the line shows all keys in one or two lines.

@FunctionKeys {
    F3  : "Exit"
    F5  : "Refresh"
    F24 : "More keys"
}

@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.