Skip to content

The format of a .dyalogbuild file

Jump to bottom
Michael Baas edited this page May 12, 2021 · 12 revisions

Each non-empty line of a DyalogBuild script has the following syntax: INSTRUCTION : argument, Parameter1=value1, Parameter2=value2,... Comment-lines starting with ⍝ are also supported.

Using Environment-Variables with $EnvVar

Everything after INSTRUCTION (every argument used) may reference environment-variables using syntax $EnvVar. You can continue with any non-alphabetic chars immediately following the name of the var, otherwise leave a blank.

Examples

  • "$Foo\Goo" => "C:\TEMP\Goo"
  • "$Git MyDir" => "c:\git\MyDir"
  • "$Git MyDir" => "c:\git\ MyDir"

Possible INSTRUCTIONs discussed below.

Warning

The logic is rather "brutal": we're looking for $ followed by any number of _,⎕A,⎕D and replace them with the value the environment returns. There currently is no way to avoid that replacement for usage of $ in strings. Please submit an issue if that is a problem.

DYALOGBUILD

DYALOGBUILD : nnn

This instruction must be included and be the first one. "nnn" specifies the minimum version required to run this script.

ID

ID : name[, Version=nnn]

This instruction is purely informational and causes a log entry of "Building name" or "Building name version nnn" where "nnn" is a number.

COPY

COPY : path1, Target=path2

Copies one or more files from path1 to path2.

NS

NS : pathname[, Target=namespace]

Loads the APL object(s) defined in the file(s) matching the pattern "pathname" into "namespace" (default is #), establishing the namespace if it does not exist.

{CLASS|APL}

{CLASS|APL}: pathname[, Target=namespace]

Loads the APL object defined in "pathname" into "namespace" (default is #).

LIB

LIB : name[, Target=namespace]

Loads the library utility "name" into "namespace" (default is #).

A "library utility" is any utility in the folder $DYALOG\Library. These tools can be loaded directly through the LIB-Command without adding pathnames.

Examples

  • LIB: InitConga, Target=#.cng

    Loads the file InitConga.dyalog into namespace #.cng

  • LIB: APLProcess

    Loads APLProcess into #.

NB: libraries were introduced with Dyalog v16 - so at least v16 will be required to handle LIB-Statement, otherwise files may not be found.

CSV

CSV : pathname, Target=matname[, ColTypes=spec]

Loads the CSV file "pathname" as a matrix called "matname". "spec" corresponds to the third element of ⎕CSV's right argument; for details, see https://help.dyalog.com/18.0/Content/Language/System%20Functions/csv.htm

DATA

DATA : pathname, Target=namespace[, Format=type[, SetEOL=nl]]

Loads the contents of the file(s) matching the pattern "pathname" into one or more variables in "namespace" (default is #). The variable(s) will be named with the base filename(s).

"type" dictates how the file content of each file is interpreted, and may be one of:

  • charvec - meaning as a simple character vector. If SetEOL=nl is specified, the lines will be separated by the chosen line ending sequence; one or more of the leftmost character codes or the corresponding decimal numbers of:

                LF   Line Feed            ⎕UCS 10    (the default)
            VT   Vertical Tab         ⎕UCS 11
            FF   Form Feed            ⎕UCS 12
            CR   Carriage Return      ⎕UCS 13
            NEL  New Line             ⎕UCS 133
            LS   Line Separator       ⎕UCS 8282
            PS   Paragraph Separator  ⎕UCS 8233

  • charvecs - meaning as a vector of character vectors

  • charmat - meaning as a character matrix

  • json - meaning as json. The variable will be a numeric scalar, a vector, or a namespace in accordance with the JSON code in the file.

LX

LX : expression

Sets the workspace's ⎕LX to "expression".

EXEC

EXEC : expression

Executes the APL expression "expression".

PROD

PROD : expression

Executes the APL expression "expression" only if ]DBuild was called with the -production modifier

DEFAULTS

DEFAULTS : "expression"

Executes the APL expression "expression" in each namespace created or accessed by the NS instruction (and in #, of course). A build-file may contain multiple DEFAULTS-statements, the expressions will be executed in the sequence they were found. To be very clear:

DEFAULTS: ⎕IO←0
NS: MyNS, Target=#.myNS
DEFAULTS: ⎕IO←1
NS: MyNS2, Target=#.myNS2

⎕IO will be set to 1 in and MyNS2 and to 0 in MyNS.

TARGET

TARGET : wsname.dws

Sets the WSID to "wsname.dws" so the workspace is ready to )SAVE. TARGET-Instructions are collected internally and are processed after all instructions in the .dyalogbuild-file have been handled and will only be processed if no errors were found processing the file.

Supports optional parameters:

  • save=0|1 (Default 0): save the workspace after a successful (=no errors were logged) build. (This setting can be modified on the commandline using modifier -save=)
  • off=0|1 (Default=0): )OFF after completion of Build. If errors were logged, a logfile (same name as the .dyalogbuild-file with .log-extension) will be created and exit code 1 will be set. (This setting can be modified on the commandline using modifier -save=)
  • type=ActiveXControl|InProcessServer|Library|NativeExe|OutOfProcessServer|StandaloneNativeExe all files that can be created using the File|Export dialog in the session can also be created using DBuild. The type parameter is mandatory when doing so.
  • flag=number Flag is the sum of the following values:

BOUND_CONSOLE | 2 BOUND_USEDOTNET | 4 BOUND_RUNTIME | 8 BOUND_XPLOOK | 32

  • resource is a filename the contents of which will be inserted as a resource in the bound file (used by ASP.NET)
  • icon is the name of an icon file, the contents of which are used as the main icon for the bound file
  • cmdline is the command line that is bound in the find and passed to dyalog.dll when the dll is started
  • details is a simple text vector which contains a ";"-separated list of ":"-separated names and values of properties that are to be shown in the "Details" tab in the Properties dialog which can be opened by right clicking on an executable in Windows Explorer. Note that none of the names or values validated. Note also that the name of the property is not necessarily the name that the program must use .. search for "string-name" in https://msdn.microsoft.com/en-us/library/windows/desktop/aa381058(v=vs.85).aspx for more details for executables. For .NET assemblies, look at https://msdn.microsoft.com/en-us/library/system.reflection(v=vs.110).aspx; any of the classes listed which has a constructor which takes a single string value as its argument should be definable.
Clone this wiki locally