From 0ac5b41f9a8ed6ac4031bea792b71bf42281a1fe Mon Sep 17 00:00:00 2001 From: jeronimoalbi Date: Fri, 8 Sep 2023 18:15:51 +0200 Subject: [PATCH 1/4] docs: change docs to use "apps" instead of "plugins" --- docs/docs/apps/01-using-apps.md | 42 +++++++ .../02-developing-apps.md} | 113 +++++++++--------- docs/docs/{plugins => apps}/_category_.json | 2 +- docs/docs/plugins/01-using-plugins.md | 43 ------- 4 files changed, 101 insertions(+), 99 deletions(-) create mode 100644 docs/docs/apps/01-using-apps.md rename docs/docs/{plugins/02-dev-plugins.md => apps/02-developing-apps.md} (65%) rename docs/docs/{plugins => apps}/_category_.json (58%) delete mode 100644 docs/docs/plugins/01-using-plugins.md diff --git a/docs/docs/apps/01-using-apps.md b/docs/docs/apps/01-using-apps.md new file mode 100644 index 0000000000..7f5aa2d44f --- /dev/null +++ b/docs/docs/apps/01-using-apps.md @@ -0,0 +1,42 @@ +--- +description: Using and Developing Ignite Apps +--- + +# Using Ignite Apps + +Apps offer a way to extend the functionality of the Ignite CLI. There are two +core concepts within apps: `Commands` and `Hooks`. `Commands` extend the CLI's +functionality and `Hooks` extend existing CLI command functionality. + +Apps are registered in an Ignite scaffolded blockchain project through the +`apps.yml`, or globally through `$HOME/.ignite/apps/apps.yml`. + +To use an app within your project execute the following command inside the +project directory: + +```sh +ignite app install github.com/project/cli-plugin +``` + +The app will be available only when running `ignite` inside the project +directory. + +To use an app globally on the other hand, execute the following command: + +```sh +ignite app install -g github.com/project/cli-plugin +``` + +The command will compile the app and make it immediately available to the +`ignite` command lists. + +## Listing installed apps + +When in an ignite scaffolded blockchain you can use the command `ignite app +list` to list all Ignite Apps and there statuses. + +## Updating apps + +When an app in a remote repository releases updates, running `ignite app +update ` will update an specific app declared in your +project's `config.yml`. diff --git a/docs/docs/plugins/02-dev-plugins.md b/docs/docs/apps/02-developing-apps.md similarity index 65% rename from docs/docs/plugins/02-dev-plugins.md rename to docs/docs/apps/02-developing-apps.md index 6cbc1b6426..bb834bb401 100644 --- a/docs/docs/plugins/02-dev-plugins.md +++ b/docs/docs/apps/02-developing-apps.md @@ -1,45 +1,46 @@ --- -description: Using and Developing plugins +description: Using and Developing Ignite Apps --- -# Developing Plugins +# Developing Ignite Apps -It's easy to create a plugin and use it immediately in your project. First -choose a directory outside your project and run : +It's easy to create an app and use it immediately in your project. First +choose a directory outside your project and run: ```sh -$ ignite plugin scaffold my-plugin +$ ignite app scaffold my-app ``` -This will create a new directory `my-plugin` that contains the plugin's code, -and will output some instructions about how to use your plugin with the -`ignite` command. Indeed, a plugin path can be a local directory, which has -several benefits: +This will create a new directory `my-app` that contains the app's code +and will output some instructions about how to use your app with the +`ignite` command. An app path can be a local directory which has several +benefits: -- you don't need to use a git repository during the development of your plugin. -- the plugin is recompiled each time you run the `ignite` binary in your -project, if the source files are older than the plugin binary. +- You don't need to use a Git repository during the development of your app. +- The app is recompiled each time you run the `ignite` binary in your + project if the source files are older than the app binary. -Thus, the plugin development workflow is as simple as : +Thus, app development workflow is as simple as: -1. scaffold a plugin with `ignite plugin scaffold my-plugin` -2. add it to your config via `ignite plugin add -g /path/to/my-plugin` -3. update plugin code -4. run `ignite my-plugin` binary to compile and run the plugin. -5. go back to 3. +1. Scaffold an app with `ignite app scaffold my-app` +2. Add it to your config via `ignite app install -g /path/to/my-app` +3. Update app code +4. Run `ignite my-app` binary to compile and run the app +5. Go back to 3 -Once your plugin is ready, you can publish it to a git repository, and the -community can use it by calling `ignite plugin add github.com/foo/my-plugin`. +Once your app is ready you can publish it to a Git repository and the +community can use it by calling `ignite app install github.com/foo/my-app`. -Now let's detail how to update your plugin's code. +Now let's detail how to update your app's code. -## The plugin interface +## App interface -The `ignite` plugin system uses `github.com/hashicorp/go-plugin` under the hood, -which implies to implement a predefined interface: +Under the hood Ignite Apps are implemented using a plugin system based on +`github.com/hashicorp/go-plugin`. + +All apps must implement a predefined interface: ```go title=ignite/services/plugin/interface.go -// An ignite plugin must implements the Plugin interface. type Interface interface { // Manifest declares the plugin's Command(s) and Hook(s). Manifest() (Manifest, error) @@ -70,24 +71,26 @@ type Interface interface { } ``` -The code scaffolded already implements this interface, you just need to update -the methods' body. - +The scaffolded code already implements this interface, you just need to update +the method's body. -## Defining plugin's manifest +## Defining app's manifest -Here is the `Manifest` struct : +Here is the `Manifest` struct: ```go title=ignite/services/plugin/interface.go type Manifest struct { Name string + // Commands contains the commands that will be added to the list of ignite // commands. Each commands are independent, for nested commands use the // inner Commands field. Commands []Command + // Hooks contains the hooks that will be attached to the existing ignite // commands. Hooks []Hook + // SharedHost enables sharing a single plugin server across all running instances // of a plugin. Useful if a plugin adds or extends long running commands // @@ -104,29 +107,28 @@ type Manifest struct { } ``` -In your plugin's code, the `Manifest` method already returns a predefined -`Manifest` struct as an example. Adapt it according to your need. +In your app's code the `Manifest` method already returns a predefined +`Manifest` struct as an example. You must adapt it according to your need. -If your plugin adds one or more new commands to `ignite`, feeds the `Commands` -field. +If your app adds one or more new commands to `ignite`, add them to the +`Commands` field. -If your plugin adds features to existing commands, feeds the `Hooks` field. +If your app adds features to existing commands, add them to the `Hooks` field. -Of course a plugin can declare `Commands` *and* `Hooks`. +Of course an app can declare both, `Commands` *and* `Hooks`. -A plugin may also share a host process by setting `SharedHost` to `true`. -`SharedHost` is desirable if a plugin hooks into, or declares long running commands. -Commands executed from the same plugin context interact with the same plugin server. +An app may also share a host process by setting `SharedHost` to `true`. +`SharedHost` is desirable if an app hooks into, or declares long running commands. +Commands executed from the same app context interact with the same app server. Allowing all executing commands to share the same server instance, giving shared execution context. -## Adding new command +## Adding new commands -Plugin commands are custom commands added to the ignite cli by a registered -plugin. Commands can be of any path not defined already by ignite. All plugin -commands will extend of the command root `ignite`. +App commands are custom commands added to Ignite CLI by an installed app. +Commands can use any path not defined already by the CLI. -For instance, let's say your plugin adds a new `oracle` command to `ignite -scaffold`, the `Manifest()` method will look like : +For instance, let's say your app adds a new `oracle` command to `ignite +scaffold`, then the `Manifest` method will look like : ```go func (p) Manifest() (plugin.Manifest, error) { @@ -149,8 +151,8 @@ func (p) Manifest() (plugin.Manifest, error) { } ``` -To update the plugin execution, you have to change the plugin `Execute` command, -for instance : +To update the app execution, you have to change the `Execute` command. For +example: ```go func (p) Execute(cmd plugin.ExecutedCommand) error { @@ -171,23 +173,24 @@ func (p) Execute(cmd plugin.ExecutedCommand) error { } ``` -Then, run `ignite scaffold oracle` to execute the plugin. +Then, run `ignite scaffold oracle` to execute the app. ## Adding hooks -Plugin `Hooks` allow existing ignite commands to be extended with new +App `Hooks` allow existing CLI commands to be extended with new functionality. Hooks are useful when you want to streamline functionality without needing to run custom scripts after or before a command has been run. -this can streamline processes that where once error prone or forgotten all +This can streamline processes that where once error prone or forgotten all together. -The following are hooks defined which will run on a registered `ignite` commands +The following are hooks defined which will run on a registered `ignite` +command: | Name | Description | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Pre | Runs before a commands main functionality is invoked in the `PreRun` scope | | Post | Runs after a commands main functionality is invoked in the `PostRun` scope | -| Clean Up | Runs after a commands main functionality is invoked. if the command returns an error it will run before the error is returned to guarantee execution. | +| Clean Up | Runs after a commands main functionality is invoked. If the command returns an error it will run before the error is returned to guarantee execution. | *Note*: If a hook causes an error in the pre step the command will not run resulting in `post` and `clean up` not executing. @@ -238,7 +241,7 @@ func (p) ExecuteHookCleanUp(hook plugin.ExecutedHook) error { } ``` -Above we can see a similar definition to `Command` where a hook has a `Name` and -a `PlaceHookOn`. You'll notice that the `Execute*` methods map directly to each -life cycle of the hook. All hooks defined within the plugin will invoke these +Above we can see a similar definition to `Command` where a hook has a `Name` +and a `PlaceHookOn`. You'll notice that the `Execute*` methods map directly to +each life cycle of the hook. All hooks defined within the app will invoke these methods. diff --git a/docs/docs/plugins/_category_.json b/docs/docs/apps/_category_.json similarity index 58% rename from docs/docs/plugins/_category_.json rename to docs/docs/apps/_category_.json index 27114924ce..5ce59790e7 100644 --- a/docs/docs/plugins/_category_.json +++ b/docs/docs/apps/_category_.json @@ -1,5 +1,5 @@ { - "label": "Plugins", + "label": "Ignite Apps", "position": 7, "link": null } diff --git a/docs/docs/plugins/01-using-plugins.md b/docs/docs/plugins/01-using-plugins.md deleted file mode 100644 index 9b830a2ef6..0000000000 --- a/docs/docs/plugins/01-using-plugins.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: Using and Developing plugins ---- - -# Using Plugins - -Ignite plugins offer a way to extend the functionality of the Ignite CLI. There -are two core concepts within plugins : `Commands` and `Hooks`. Where `Commands` -extend the cli's functionality, and `Hooks` extend existing command -functionality. - -Plugins are registered in an Ignite scaffolded Blockchain project through the -`plugins.yml`, or globally through `$HOME/.ignite/plugins/plugins.yml`. - -To use a plugin within your project, execute the following command inside the -project directory: - -```sh -ignite plugin add github.com/project/cli-plugin -``` - -The plugin will be available only when running `ignite` inside the project -directory. - -To use a plugin globally on the other hand, execute the following command: - -```sh -ignite plugin add -g github.com/project/cli-plugin -``` - -The command will compile the plugin and make it immediately available to the -`ignite` command lists. - -## Listing installed plugins - -When in an ignite scaffolded blockchain you can use the command `ignite plugin -list` to list all plugins and there statuses. - -## Updating plugins - -When a plugin in a remote repository releases updates, running `ignite plugin -update ` will update a specific plugin declared in your -project's `config.yml`. From 46039615ea1cf7afcec0fd8b3ac56256d509dcea Mon Sep 17 00:00:00 2001 From: jeronimoalbi Date: Fri, 8 Sep 2023 18:33:31 +0200 Subject: [PATCH 2/4] chore: correct plugin reference --- docs/docs/apps/01-using-apps.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/apps/01-using-apps.md b/docs/docs/apps/01-using-apps.md index 7f5aa2d44f..defda177a0 100644 --- a/docs/docs/apps/01-using-apps.md +++ b/docs/docs/apps/01-using-apps.md @@ -15,7 +15,7 @@ To use an app within your project execute the following command inside the project directory: ```sh -ignite app install github.com/project/cli-plugin +ignite app install github.com/project/cli-app ``` The app will be available only when running `ignite` inside the project @@ -24,7 +24,7 @@ directory. To use an app globally on the other hand, execute the following command: ```sh -ignite app install -g github.com/project/cli-plugin +ignite app install -g github.com/project/cli-app ``` The command will compile the app and make it immediately available to the From 66ecba3ed77b8794d2474988b3cdc504dece8383 Mon Sep 17 00:00:00 2001 From: jeronimoalbi Date: Wed, 20 Sep 2023 19:09:52 +0200 Subject: [PATCH 3/4] chore: change app examples to use `app` as the type name --- docs/docs/apps/02-developing-apps.md | 33 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/docs/apps/02-developing-apps.md b/docs/docs/apps/02-developing-apps.md index bb834bb401..1f5a13a508 100644 --- a/docs/docs/apps/02-developing-apps.md +++ b/docs/docs/apps/02-developing-apps.md @@ -42,10 +42,10 @@ All apps must implement a predefined interface: ```go title=ignite/services/plugin/interface.go type Interface interface { - // Manifest declares the plugin's Command(s) and Hook(s). + // Manifest declares app's Command(s) and Hook(s). Manifest() (Manifest, error) - // Execute will be invoked by ignite when a plugin Command is executed. + // Execute will be invoked by ignite when an app Command is executed. // It is global for all commands declared in Manifest, if you have declared // multiple commands, use cmd.Path to distinguish them. Execute(cmd ExecutedCommand) error @@ -91,18 +91,19 @@ type Manifest struct { // commands. Hooks []Hook - // SharedHost enables sharing a single plugin server across all running instances - // of a plugin. Useful if a plugin adds or extends long running commands + // SharedHost enables sharing a single app server across all running instances + // of an app. Useful if an app adds or extends long running commands // - // Example: if a plugin defines a hook on `ignite chain serve`, a plugin server is instanciated + // Example: if an app defines a hook on `ignite chain serve`, a server is instanciated // when the command is run. Now if you want to interact with that instance from commands - // defined in that plugin, you need to enable `SharedHost`, or else the commands will just - // instantiate separate plugin servers. + // defined in that app, you need to enable `SharedHost`, or else the commands will just + // instantiate separate app servers. // - // When enabled, all plugins of the same `Path` loaded from the same configuration will - // attach it's rpc client to a an existing rpc server. + // When enabled, all apps of the same `Path` loaded from the same configuration will + // attach it's gRPC client to a an existing gRPC server. // - // If a plugin instance has no other running plugin servers, it will create one and it will be the host. + // If an app instance has no other running app servers, it will create one and it + // will be the host. SharedHost bool `yaml:"shared_host"` } ``` @@ -131,7 +132,7 @@ For instance, let's say your app adds a new `oracle` command to `ignite scaffold`, then the `Manifest` method will look like : ```go -func (p) Manifest() (plugin.Manifest, error) { +func (app) Manifest() (plugin.Manifest, error) { return plugin.Manifest{ Name: "oracle", Commands: []plugin.Command{ @@ -155,7 +156,7 @@ To update the app execution, you have to change the `Execute` command. For example: ```go -func (p) Execute(cmd plugin.ExecutedCommand) error { +func (app) Execute(cmd plugin.ExecutedCommand) error { if len(cmd.Args) == 0 { return fmt.Errorf("oracle name missing") } @@ -198,7 +199,7 @@ resulting in `post` and `clean up` not executing. The following is an example of a `hook` definition. ```go -func (p) Manifest() (plugin.Manifest, error) { +func (app) Manifest() (plugin.Manifest, error) { return plugin.Manifest{ Name: "oracle", Hooks: []plugin.Hook{ @@ -210,7 +211,7 @@ func (p) Manifest() (plugin.Manifest, error) { }, nil } -func (p) ExecuteHookPre(hook plugin.ExecutedHook) error { +func (app) ExecuteHookPre(hook plugin.ExecutedHook) error { switch hook.Name { case "my-hook": fmt.Println("I'm executed before ignite chain build") @@ -220,7 +221,7 @@ func (p) ExecuteHookPre(hook plugin.ExecutedHook) error { return nil } -func (p) ExecuteHookPost(hook plugin.ExecutedHook) error { +func (app) ExecuteHookPost(hook plugin.ExecutedHook) error { switch hook.Name { case "my-hook": fmt.Println("I'm executed after ignite chain build (if no error)") @@ -230,7 +231,7 @@ func (p) ExecuteHookPost(hook plugin.ExecutedHook) error { return nil } -func (p) ExecuteHookCleanUp(hook plugin.ExecutedHook) error { +func (app) ExecuteHookCleanUp(hook plugin.ExecutedHook) error { switch hook.Name { case "my-hook": fmt.Println("I'm executed after ignite chain build (regardless errors)") From c48146ba8ee0159b1d254465be1b3d228e4c03bf Mon Sep 17 00:00:00 2001 From: jeronimoalbi Date: Mon, 25 Sep 2023 09:39:19 +0200 Subject: [PATCH 4/4] chore: restore apps config name references back to `plugins.yml` --- docs/docs/apps/01-using-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/apps/01-using-apps.md b/docs/docs/apps/01-using-apps.md index defda177a0..1741496952 100644 --- a/docs/docs/apps/01-using-apps.md +++ b/docs/docs/apps/01-using-apps.md @@ -9,7 +9,7 @@ core concepts within apps: `Commands` and `Hooks`. `Commands` extend the CLI's functionality and `Hooks` extend existing CLI command functionality. Apps are registered in an Ignite scaffolded blockchain project through the -`apps.yml`, or globally through `$HOME/.ignite/apps/apps.yml`. +`plugins.yml`, or globally through `$HOME/.ignite/plugins/plugins.yml`. To use an app within your project execute the following command inside the project directory: