Usage

When invoking afwdev, you may specify general options, followed by a subcommand, followed by subcommand-specific options.

afwdev [options...] {subcommand} [subcommand-options...]

Command afwdev is a development tool used to create, extend, maintain, and test an Adaptive Framework (AFW) Package.

An AFW package can be the one that holds the AFW core (afw) or other AFW packages that contains AFW applications, commands, extensions, layouts, servers, test data, etc.

General Options

The following are a list of general options, which may be used for all subcommands:

Subcommands

The following subcommands are available:

add-adaptor-type

This will add skeletons for the basic interfaces afw_adaptor_factory, afw_adaptor, and afw_adaptor_session for a new adaptor type to an existing srcdir. The implementation_id specified will be the adaptor type. If additional interfaces are needed, use subcommand add-core-interface.

The following options may be used for the add-adaptor-type subcommand:

add-content-type

This will add skeletons for interfaces afw_content_type and afw_content_type_object_list_writer for a new content type to an existing srcdir, plus add a .c to generate/manifest/content_type/. The implementation_id specified will be the content type id.

The following options may be used for the add-content-type subcommand:

add-core-interface

This will add a skeleton for a core interface to an existing scrdir.

The following options may be used for the add-core-interface subcommand:

add-log-type

This will add the skeletons for the interfaces afw_log_factory and afw_log for a new log type to and existing srcdir. The implementation_id specified will be the log type id. If additional interfaces are needed, use subcommand add-core-interface.

The following options may be used for the add-log-type subcommand:

afwdev-parser-info

This subcommand will write the info used for afwdev argument parse to json.

The following options may be used for the afwdev-parser-info subcommand:

build

This subcommand will build an AFW package using information from the afw-package.json file.

The build switches --cmake, --docker, --docs, --js provide build type context that other switches, such as --clean, --install, and --generate will execute under. The --all selects all of those contexts.

The following options may be used for the build subcommand:

ebnf

This will generate EBNF diagrams from core syntax.ebnf.

for

This will run a command in a set of directories identified by the --set-name argument.

The set name is the name of the settings['forSets'] property that has the list of directories to use.

Use the afwdev settings command and its --help for more information.

The following options may be used for the for subcommand:

generate

Process generate/ directories. The SRCDIR_PATTERN is based on a subset of the rules used by unix shell and indicates that all matching directories that contain a generate/ directory should be processed. See src/afwdev/doc/generate.txt in the AdaptiveFramework core package for more information.

The following options may be used for the generate subcommand:

make-afw-package

This will make a new skeleton Adaptive Framework AFW package directory. The implementation_id specified will be the AFW Package Id and afw_package_dir_path it the new AFW packages directory path. An AFW package can hold AFW applications, commands, extensions, etc. The first afwdev make-extension issued in this AFW package will hold the package's manifest.

The following options may be used for the make-afw-package subcommand:

make-command

This will make a new command skeleton directory. The implementation_id specified will be the command name. Although more common for extensions, add-* subcommands can be used to add interfaces to this command.

The following options may be used for the make-command subcommand:

make-extension

This will make a new extension skeleton directory that can hold implementations of AFW interfaces. The implementation_id specified will be the extension id. Use add-* subcommands to add interfaces to this extension.

The following options may be used for the make-extension subcommand:

settings

This will print the settings used by afwdev. " An "afwdev-settings.json" and/or an "afw.code-space" file located in the current AFW package directory, one of its parents or your home directory is used to produce these settings when afwdev starts. If none of these files exist, settings apply to your current AFW package directory.

Information from "afwdev-settings.json" is load into settings first then normalized.

If the "afwPackages" property does not exist, it will be constructed from paths in the folders of "afw.code-space" that contain an "afw-package.json" file or with a single entry for the current AFW package's root directory.

If a "forSets['default']" property doesn't exist, one is created with all of the paths in "afwPackages".

All paths in settings are normalized to their full path with a '/' at the end of all directory names.

The path to the "code-space" file can be explicitly specified with a "code_workspace_path" property in "afwdev-settings.json".

The default make --jobs argument for afwdev build can be specified with the "make_jobs_argument" property. For example, "make_jobs_argument":"--jobs 4" will run make using 4 threads if the -jobs argument is not specified on afwdev build.

task

This will run the command(s) supplied by the "tasks" object property of afwdev-settings.json with a property name matching the specified task_name. Multiple commands can be separated by "&&". The failure of a command will cause the remaining commands to be skipped.

The following options may be used for the task subcommand:

test

Run tests for one more more source directories.

The following options may be used for the test subcommand:

validate

This command will validate json files using JSON Schemas in the generate/schemas/afw/ directory.

The pattern of objects to be validated are specified using the --pattern argument. The default for pattern is "src/*/generate*/objects/*/*.json".

This pattern can have "*", "?", and "**" wildcards, much like Unix style pathname patterns. The "**" wildcard will match any number of directories and subdirectories. For example, the pattern "src/**/objects/*/*.json" will match all *.json files in the objects/ directory of any subdirectory of the src/ package directory. '*' will match any number of characters except a '/' and '?' will match any single character except a '/'.

If the pattern starts with a "/", it will be treated as an absolute path. If it does not start with a "/", it will be treated as a relative path within the afw package root directory that afwdev is operating on.

If a json file contains a "$schema" property, the value of that property will be used to determine the schema to use. Otherwise, the schema will be determined by the parent directory of the file. For example, if the json file is in the "src/afw/generate/objects/_AdaptiveDataType_" directory, the "_AdaptiveDataType_.json" schema in the "generated/schemas/afw/" directory will be used.

The following options may be used for the validate subcommand:

Examples

Directory structure of an AFW package
-------------------------------------

The basic structure of an AFW package is:

<AFW package root directory>
|-- doc/                         # Generated docs                   
|-- generated/                   # Produced by generate subcommand
|   |-- *.cmake                  # Generated cmake files
|-- src/                         # Commonly src/ contains source directories
|   |-- <SRCDIR>/                # One or more command, extension, or server
|       |-- generate/            # Processed by generate subcommand
|       |-- generated/           # Produced by generate subcommand
|       |   |-- c source         # Generated *.h and .c files
|       |   |-- *.cmake          # Generated cmake files
|       |   |-- ...              # Other generated files and directories
|       |-- c source             # <SRCDIR>_*.h and .c files
|       |-- CMakeLists.txt       # CMakeLists.txt for <SRCDIR>
|       |-- ...                  # Other source files and directories
|-- .editorconfig                # Source editor coding style
|-- .gitattributes               # Command git attributes for pathnames
|-- .gitignore                   # Command git files to ignore
|-- afw-package.json             # AFW package file managed by the afwdev
|-- CMakeLists.txt               # Root CMakeLists.txt for afw package
|-- COPYING                      # Licensing information.
|-- Doxyfile                     # Doxygen configuration file
|-- LICENSE                      # The license.
|-- package.json                 # Used to build a JavaScript package
|-- <PACKAGE_ID>_git_info.sh     # Used to produce <PACKAGE_ID>_git_info.h
|-- <PACKAGE_ID>_git_info.h      # Header file containing git information
|-- README.md                    # Repository README.md
|-- miscellaneous directories    # Other directories
|-- miscellaneous files          # Other files

Zero or more <SRCDIR> directories can exist.  Each <SRCDIR> contains the
source for one command, extension, or server implementation provided by the
AFW package. There can also be <SRCDIR> directories for other buildtypes.
This information is kept in afw-package.json.

All make-* subcommands make a new directory. The make-afw-package subcommand
makes a skeleton package directory that includes an afw-package.json file.
The other make-* subcommands make a skeleton directory in the src/ directory
and adds an entry to the afw-package.json "srcdir" property.

All add-* subcommands expect an existing "srcdir" entry in the afw-package.json
file that is either their implementation id or the value specified with the
--srcdir argument.

All add-* and make-* subcommands produces files with @todo comments that
should be searched for and replaced as appropriate.

If certain optional arguments are not specified, a prompt will occur that
allows the default value to be overridden. If the --noprompt argument is
specified or the specific optional argument is defined to never prompt, this
prompting will not occur. Specify the --prompt argument to insure prompting
occurs for all missing optional parameters.

Examples
--------

1) Make an AFW package "mypackage" in directory ~/mypackage:

    afwdev make-afw-package mypackage ~/mypackage

2) Make an extension "myextension" srcdir in "mypackage":

    cd ~/mypackage
    afwdev make-extension myextension

3) Add an adaptor type with id "myadaptor" to "myextension":

    cd ~/mypackage
    afwdev add-adaptor-type myadaptor --srcdir myextension

4) Make command "mycommand" srcdir in "mypackage":

    cd ~/mypackage
    afwdev make-command mycommand

5) Generate afwdev maintained files for "mypackage" after changes:

    cd ~/mypackage
    afwdev generate --srcdir-pattern \*

6) Run tests defined in "mypackage":

    cd ~/mypackage
    afwdev test --srcdir-pattern \*

7) Run tests defined in "mypackage" and show only errors:

    cd ~/mypackage
    afwdev test --errors --srcdir-pattern \*