@bud-tools/cli NPM

Outline

Description

The @bud-tools/cli package provides helpful scripts and commands for extension and application development. The contributed budtools, is a command line tool to manage BudTools-based applications.

Getting Started

Install @bud-tools/cli as a dev dependency in your application.

With yarn:

yarn add @bud-tools/cli@next --dev

With npm:

npm install @bud-tools/cli@next --save-dev

Configure

A BudTools-based application can be configured via the budtools property as described in the application's package.json.

Application Properties

It is possible Application Properties for a given application.\ For example, an application can define it's applicationName using the following syntax:

"budtools": {
    "frontend": {
      "config": {
        "applicationName": "Custom Application Name",
      }
    }
  },

Default Preferences

If required, an application can define for a given preference, the default value. For example, an application can update the preference value for files.enableTrash based on it's requirements:

"budtools": {
    "frontend": {
      "config": {
        "preferences": {
          "files.enableTrash": false
        }
      }
    }
  },

Default Theme

Default color and icon themes can be configured in budtools.frontend.config section:

"budtools": {
    "frontend": {
      "config": {
        "defaultTheme": "light",
        "defaultIconTheme": "vs-seti"
      }
    }
  },

Build Target

The following targets are supported: browser and electron. By default browser target is used. The target can be configured in the package.json via budtools/target property, e.g:

{
    "budtools": {
        "target": "electron"
    },
    "dependencies": {
        "@bud-tools/electron": "latest"
    }
}

For electron target applications, is it mandatory to include Electron runtime dependencies. The @bud-tools/electron package is the easiest way to install the necessary dependencies.

Electron Frontend Application Config

The electron frontend application configuration provides configuration options for the electron target.\ The currently supported configurations are:

disallowReloadKeybinding: if set to true, reloading the current browser window won't be possible with the Ctrl/Cmd + r keybinding. It is false by default. Has no effect if not in an electron environment.
windowOptions: override or add properties to the electron windowOptions.

{
    "budtools": {
        "target": "electron",
        "frontend": {
            "config": {
                "electron": {
                    "disallowReloadKeybinding": true,
                    "windowOptions": {
                        "titleBarStyle": "hidden",
                        "webPreferences": {
                            "webSecurity": false,
                            "nodeIntegration": true,
                            "webviewTag": true
                        }
                    }
                }
            }
        }
    }
}

Using Latest Builds

If you set next in your budtools config, then BudTools will prefer next over latest as the latest tag.

{
    "budtools": {
        "next": "true"
    }
}

Building

Build

The following command can be used to build the application:

Development

budtools build --mode development

Production

budtools build

Watch

The following command can be used to rebuild the application on each change:

budtools build --watch --mode development

Clean

The following command can be used to clean up the build result:

In order to clean up the build result:

budtools clean

Arguments are passed directly to webpack. Use --help to learn which options are supported.

Rebuilding Native Modules

In order to run Electron targets, one should rebuild native node modules for an electron version:

budtools rebuild

To rollback native modules, change the target to browser and run the command again.

Running

To run the backend server:

budtools start

For the browser target a server is started on http://localhost:3000 by default. For the electron target a server is started on localhost host with the dynamically allocated port by default.

Arguments are passed directly to a server, use --help to learn which options are supported.

Debugging

To debug the backend server:

budtools start --inspect

BudTools CLI accepts --inspect node flag: https://nodejs.org/en/docs/inspector/#command-line-options.

Testing

Enabling Tests

First enable expose-loader in webpack.config.js to expose modules from bundled code to tests by un-commenting:

/**
 * Expose bundled modules on window.budtools.moduleName namespace, e.g.
 * window['budtools']['@bud-tools/core/lib/common/uri'].
 * Such syntax can be used by external code, for instance, for testing.
config.module.rules.push({
    test: /\.js$/,
    loader: require.resolve('@bud-tools/application-manager/lib/expose-loader')
}); */

After that run budtools build again to expose modules in generated bundle files.

Writing Tests

See API Integration Testing docs.

Running Tests

To start the backend server and run API tests against it:

budtools test

After running test this command terminates. It accepts the same arguments as start command, but as well additional arguments to specify test files, enable inspection or generate test coverage.

Configuring Tests

To specify test files:

budtools test . --test-spec=./test/*.spec.js --plugins=./plugins

This command starts the application with a current directory as a workspace, load VS Code extensions from ./plugins and run test files matching ./test/*.spec.js glob.

Use budtools test --help to learn more options. Test specific options start with --test-.

Inspecting Tests

To inspect tests:

budtools test . --test-spec=./test/*.spec.js --test-inspect --inspect

This command starts the application server in the debug mode as well as open the Chrome devtools to debug frontend code and test files. One can reload/rerun code and tests by simply reloading the page.

Important! Since tests are relying on focus, while running tests keep the page focused.

Reporting Test Coverage

To report test coverage:

budtools test . --test-spec=./test/*.spec.js --test-coverage

This command executes tests and generate test coverage files consumable by Istanbul.

Downloading Plugins

The @bud-tools/cli package provides a utility for applications to define and download a list of plugins it requires as part of their application using the command:

budtools download:plugins

This utility works by declaring in the package.json a location to store downloaded plugins, as well defining each plugin the application wishes to download.

The property budtoolsPluginsDir describes the location of which to download plugins (relative to the package.json), for example:

"budtoolsPluginsDir": "plugins",

The property budtoolsPlugins describes the list of plugins to download, for example:

"budtoolsPlugins": {
    "vscode.theme-defaults": "https://open-vsx.org/api/vscode/theme-defaults/1.62.3/file/vscode.theme-defaults-1.62.3.vsix",
    "vscode-builtin-extension-pack": "https://open-vsx.org/api/eclipse-bud-tools/builtin-extension-pack/1.50.0/file/eclipse-bud-tools.builtin-extension-pack-1.50.0.vsix",
    "vscode-editorconfig": "https://open-vsx.org/api/EditorConfig/EditorConfig/0.14.4/file/EditorConfig.EditorConfig-0.14.4.vsix",
    "vscode-eslint": "https://open-vsx.org/api/dbaeumer/vscode-eslint/2.1.1/file/dbaeumer.vscode-eslint-2.1.1.vsix",
}

Please note that in order to use extensionPacks properly you should use namespace.name as the id you give extensions so that when resolving the pack we do not re-download an existing plugin under a different name.

The property budtoolsPluginsExcludeIds can be used to declare the list of plugin ids to exclude when using extension-packs. The ids referenced by the property will not be downloaded when resolving extension-packs, and can be used to omit extensions which are problematic or unwanted. The format of the property is as follows:

"budtoolsPluginsExcludeIds": [
  "vscode.cpp"
]

Autogenerated Application

This package can auto-generate application code for both the backend and frontend, as well as webpack configuration files.

When targeting Electron, the electron-main.js script will spawn the backend process in a Node.js sub-process, where Electron's API won't be available. To prevent the generated application from forking the backend, you can pass a --no-cluster flag. This flag is mostly useful/used for debugging.

# when developing a BudTools application with @bud-tools/cli:
yarn budtools start --no-cluster

# when starting a bundled application made using @bud-tools/cli:
bundled-application.exe --no-cluster

Additional Information

License

Trademark

"BudTools" is a trademark of the Eclipse Foundation https://www.eclipse.org/budtools

@infinitebrahmanuniverse/nolb-_bud @zalastax/nolb-_bud

0.0.3

1 year ago

0.0.2

1 year ago

0.0.1

2 years ago