Using Wharf for automatic porting

You can use Wharf to automatically fix build errors caused by packages or modules that don't support z/OS® by investigating type checking errors and updating module dependencies or retagging files to include missing function, variable, constant, or type definitions.

The Wharf program can help you with the following tasks:
  • Port existing packages or modules in a workspace
  • Port dependencies of modules (dependencies will be moved inside workspace)
  • Provide insights into possible issues with the package or module
  • Make edits and run commands to ensure the package or module can be installed on z/OS without error

Usage

Run Wharf similarly to go build with the following command:
wharf [-d] [-v] [-t] [-tags] <packages>
Wharf only supports executing within a workspace, which means operating similarly to go build -mod=readonly with the following considerations:
  • Must be inside a Go workspace (initialize one in your current folder by running go work init)
  • The package or module to port must exist inside a workspace

Flag

Use the following flags to control the behavior of Wharf:
-n
Dry-run mode; disables edits, script will only make suggestions
-t
Run unit tests found in packages or modules that were altered and output their result (ignored if in dry-run mode)
-v
Enable verbose output

Understanding the main porting process of Wharf

Wharf works by first loading the environment using go list and gathering information related to the package or module structures. This occurs in internal/packages, which acts almost as a special purpose compiler front-end implementation.

Type-checking occurs after the loading. Packages or modules are type checked until the first error occurs, at which the porting process begins for that package.

Packages or modules are ported based on the structure of the dependency tree. Packages or modules that are higher up in the dependency tree, that is those have fewer levels of sub-dependencies, will be ported first.

Basic steps using Wharf for porting modules

To get Wharf execute, use this command:
go install github.com/zosopentools/wharf@latest

If you're using the default GOPATH, then make sure ~/go/bin is on your PATH.

Take the following steps to port the modules:
  1. Create a directory to serve as your workspace and change directory to that workspace.
    
mkdir workspace
cd workspace
  2. Execute go work init to initialize the workspace.
  3. Clone the module you wish to port:
    git clone <url of module>
  4. Add the module to the workspace:
    go work use ./<module name>
  5. Port the module with the Wharf tool:
    wharf ./<module name>/...
  6. If no error occurs, execute go install ./<module name>/... to install the module and all its sub modules.

For details, see Using Wharf for porting applications.