Workflows
Developer uses git repositories for version control of items under development. There are two primary development workflows, making slightly different use of the underlying git repositories. Both workflows have their own advantages and disadvantages.
Files and folders
Developer will work with any existing repositories of q code. Simply clone the repository
into Developer with New > Clone Repository...
from the sidebar context menu. The
repository will appear as expected as a collection of files within collapsible folders.
Regular repositories can also be created in Developer with New > Repository...
from the sidebar
context menu.
Within this workflow, a user can enjoy the regular benefits of development within Developer
including interactive development of q scripts through either selecting code to execute
or running each script entirely with Run Script
from the q editor context menu.
Operations are version controlled on the underlying repository, and can be pushed back with Git > Push...
from the sidebar context menu.
Modules
In addition to files and folders, Developer supports a concept of modules
within the UI.
Using modules does not require a new repository type: adding a module to a repository will create a
kxscm/
directory in the underlying repository to store the module contents. This way, files and
folders can be used with modules in a single repository if desired.
A module is essentially a granular view of a single q script. Each function and data assignment that would exist within a q script file are instead stored as separate elements within the UI. For example, a script with the follow q contents:
\d .module
f1: { f2[] }
f2: { x }
data: (::)
\d .
Could be represented as a module in Developer as the following configuration:
These modules, functions, and data artifacts can be created with
New > Module
,New > Function
, etc from the context menu under any repository in the sidebar.
Notice that the definitions within the editors do not contain an assignment. The assignment is implicit from
the name of the artifact (.module.f1
for example).
Advantages
Using modules rather than scripts has some advantages:
Live
Changes made to a function or data item are live on the process as soon as they are saved. This
is not true for scripts which need to be run (using Run Script
from the context menu).
Contextual editing
Artifacts in modules with names that begin with a .
, such as .module
are defined within the namespace
of the corresponding name \d .module
. Additionally, any code executed using Display
, Evaluate
,
or Inspect
from an editor within a module will be executed within the namespace as well, so
names do not need to be qualified for interactive editing.
Artifacts in modules with names that do not begin with a .
are defined globally.
Granular uses
search
Since functions and data items are stored separately, there are UI elements aiding in exploring
q code. From any module artifact's editor or sidebar (function or data) right-clicking and
selecting Code > Uses
, or Uses (File)
will display all other functions and data items from
any modules that make use of the selection. Additionally, a search of u:.module.f1
will do the
same: search for all artifacts that use the function .module.f1
.
Granular version control
In addition, each function and data item are versioned separately. Seeing all of the changes for a single function, or reverting only a single function is simple.
Test discovery
When using modules, if a convention is followed, right-clicking a function editor and selecting
Test
will run tests relating to the function. The convention required for this is each module
to be accompanied by a module of the same name with .test
appended which contains the qcumber
tests for the module. Within the *.test
module, files should be named with the name of the function
that they test.
.module
f1
.module.test
f1.quke
As shown in the repository below.
Mix q scripts and modules
Modules can contain q scripts, and can co-exist in repositories that use regular folders and files as well.
Conversion
It is possible to convert between the two workflows (scripts and modules) within Developer.
Script to module
If using regular q scripts, the scripts can be converted to modules by either:
- Right-clicking the q script within Developer and selecting
New > Module From Q File
, or - Right-clicking a repository, selecting
New
, choosing to upload either a local or remote q script, and clicking theImport q scripts as modules ...
checkbox.
Module to script
If using modules, it is possible to convert to regular scripts, potentially for use outside of Developer:
- Right-click a module and select
New > Q File From Module
Additionally, this transformation can be done from a command line script for use as part of an
automated build process (axrepo.q_
). See the build utilities for more
information and examples.