diff --git a/PLUGIN.md b/PLUGIN.md new file mode 100644 index 000000000..680a40744 --- /dev/null +++ b/PLUGIN.md @@ -0,0 +1,20 @@ +# EMQ X plugins + +Starting from EMQ X 5.0, plugins are developed in independent projects. + +This is different from EMQ X 4.3 (and later 4.x releases) for which the plugins have to +be developed inside the emqx.git umbrella project. + +## Erlang + +### How to build a plugin + +Take [emqx-plugin-template](https://github.com/emqx/emqx-plugin-template) for reference. + +### How to deploy + +TODO + +## Elixir + +TODO diff --git a/README-CN.md b/README-CN.md index 0631a845c..00f997f4a 100644 --- a/README-CN.md +++ b/README-CN.md @@ -121,8 +121,7 @@ DIALYZER_ANALYSE_APP=emqx_lwm2m,emqx_authz make dialyzer ### 插件开发 -如果想集成或开发你自己的插件,参考 [lib-extra/README.md](./lib-extra/README.md) - +如果想集成或开发你自己的插件,参考 [PLUGIN.md](./PLUGIN.md) ### 联系我们 diff --git a/README-JP.md b/README-JP.md index 57c9a1809..058a45a95 100644 --- a/README-JP.md +++ b/README-JP.md @@ -114,7 +114,7 @@ DIALYZER_ANALYSE_APP=emqx_lwm2m,emqx_authz make dialyzer ### 自作プラグイン -プラグインを自作することができます。[lib-extra/README.md](./lib-extra/README.md)をご確認ください。 +プラグインを自作することができます。[PLUGIN.md](./PLUGIN.md) をご確認ください。 ## MQTTの仕様について diff --git a/README-RU.md b/README-RU.md index 6707ef939..9991f101d 100644 --- a/README-RU.md +++ b/README-RU.md @@ -124,8 +124,7 @@ DIALYZER_ANALYSE_APP=emqx_lwm2m,emqx_authz make dialyzer ### Разработка плагинов -Инструкция по разработке собственных плагинов доступна по ссылке: [lib-extra/README.md](./lib-extra/README.md) - +Инструкция по разработке собственных плагинов доступна по ссылке: [PLUGIN.md](./PLUGIN.md) ## Спецификации стандарта MQTT diff --git a/README.md b/README.md index bf3d93b64..d51a0f350 100644 --- a/README.md +++ b/README.md @@ -123,8 +123,7 @@ For more organised improvement proposals, you can send pull requests to [EIP](ht ### Plugin development -To develop your own plugins, see [lib-extra/README.md](./lib-extra/README.md) - +See [PLUGIN.md](./PLUGIN.md) ## MQTT Specifications diff --git a/lib-extra/README.md b/lib-extra/README.md deleted file mode 100644 index 4127b53bc..000000000 --- a/lib-extra/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# EMQ X Extra plugin apps - -This directory keeps a `plugins` file which defines all the approved -external plugins from open-source community. - -The (maybe broken) symlinks are keept to help testing plugins -in this umbrella project. - -## Add a plugin to the project - -Add `plugin_foo` as a rebar3 dependency in `plugins` file. - -e.g. For an Erlang plugin named `plugin_foo`: - -``` -{erlang_plugins, - [ {plugin_foo, {git, "https://github.com/bar/plugin-foo.git", {tag, "0.1.0"}}} - ] -}. -``` - -Note: The `-emqx_plugin(?MODULE)` attribute should be added to -`_app.erl` file to indicate that this is an EMQ X Broker plugin. - -For example: -```erlang -%% plugin_foo_app.erl --emqx_plugin(?MODULE) -``` - -## Build a release - -``` -$ export EMQX_EXTRA_PLUGINS=plugin_foo,plugin_bar -$ make -``` - -If all goes as expected, there should be two directories in the release: - -``` -_build/emqx/rel/emqx/lib/plugin_foo-<..vsn..>/ -``` - -## Run your code - -Start the node (interactive mode) - -``` -./_build/emqx/rel/emqx/bin/emqx console -``` - -Load the plugin with command: - -``` -./_build/emqx/rel/emqx/bin/emqx_ctl plugins load plugin_foo -``` - -## Test the plugin - -If the plugin is added as a rebar dependency, it should be cloned -to `_build/default/lib/plugin_foo`. - -Before you can test it, you need to make sure there is a symlink -in `lib-extra` pointing to the clone. For instance, the `emqx_plugin_template` -plugin is linked like this - -`emqx_plugin_template -> ../_build/default/lib/emqx_plugin_template/` - -To run its teste cases: - -```bash -./rebar3 eunit --dir lib-extra/plugin_foo -mkae lib-extra/plugin_foo-ct -``` - -NOTE: we should `depth=1` shallow clone into `_build/` directory, -for plugins being actively developed, you can place the clone in `lib-extra/` - -## Caveats - -* Elixir dependency in Erlang is not quite nicely supported as incremental builds, - meaning you will not be able to edit the code in this project and get recompiled - in the next `make` command. - -* To have the plugin enabled/loaded by default, you can include it in the template - `data/loaded_plugins.tmpl` diff --git a/lib-extra/emqx_plugin_template b/lib-extra/emqx_plugin_template deleted file mode 120000 index 6cf8106d2..000000000 --- a/lib-extra/emqx_plugin_template +++ /dev/null @@ -1 +0,0 @@ -../_build/default/lib/emqx_plugin_template \ No newline at end of file diff --git a/lib-extra/plugins b/lib-extra/plugins deleted file mode 100644 index 6c0f1d9f0..000000000 --- a/lib-extra/plugins +++ /dev/null @@ -1,9 +0,0 @@ -{erlang_plugins, - [ {emqx_plugin_template, {git, "https://github.com/emqx/emqx-plugin-template", {tag, "4.3.0"}}} - ] -}. - -{elixir_plugins, - [ {emqx_elixir_plugin, {git, "https://github.com/emqx/emqx-elixir-plugin.git", {branch, "3.0.0"}}} - ] -}. diff --git a/rebar.config.erl b/rebar.config.erl index b73a7a740..dbaf9d6a3 100644 --- a/rebar.config.erl +++ b/rebar.config.erl @@ -5,9 +5,9 @@ do(Dir, CONFIG) -> case iolist_to_binary(Dir) of <<".">> -> - {HasElixir, C1} = deps(CONFIG), + C1 = deps(CONFIG), Config = dialyzer(C1), - maybe_dump(Config ++ [{overrides, overrides()}] ++ coveralls() ++ config(HasElixir)); + maybe_dump(Config ++ [{overrides, overrides()}] ++ coveralls() ++ config()); _ -> CONFIG end. @@ -22,40 +22,13 @@ deps(Config) -> {deps, OldDeps} = lists:keyfind(deps, 1, Config), MoreDeps = [bcrypt() || provide_bcrypt_dep()] ++ [quicer() || is_quicer_supported()], - {HasElixir, ExtraDeps} = extra_deps(), - {HasElixir, lists:keystore(deps, 1, Config, {deps, OldDeps ++ MoreDeps ++ ExtraDeps})}. - -extra_deps() -> - {ok, Proplist} = file:consult("lib-extra/plugins"), - ErlPlugins0 = proplists:get_value(erlang_plugins, Proplist), - ExPlugins0 = proplists:get_value(elixir_plugins, Proplist), - Filter = string:split(os:getenv("EMQX_EXTRA_PLUGINS", ""), ",", all), - ErlPlugins = filter_extra_deps(ErlPlugins0, Filter), - ExPlugins = filter_extra_deps(ExPlugins0, Filter), - {ExPlugins =/= [], ErlPlugins ++ ExPlugins}. - -filter_extra_deps(AllPlugins, ["all"]) -> - AllPlugins; -filter_extra_deps(AllPlugins, Filter) -> - filter_extra_deps(AllPlugins, Filter, []). -filter_extra_deps([], _, Acc) -> - lists:reverse(Acc); -filter_extra_deps([{Plugin, _} = P | More], Filter, Acc) -> - case lists:member(atom_to_list(Plugin), Filter) of - true -> - filter_extra_deps(More, Filter, [P | Acc]); - false -> - filter_extra_deps(More, Filter, Acc) - end. + lists:keystore(deps, 1, Config, {deps, OldDeps ++ MoreDeps}). overrides() -> [ {add, [ {extra_src_dirs, [{"etc", [{recursive,true}]}]} , {erl_opts, [{compile_info, [{emqx_vsn, get_vsn()}]}]} ]} - ] ++ snabbkaffe_overrides() ++ community_plugin_overrides(). - -community_plugin_overrides() -> - [{add, App, [ {erl_opts, [{i, "include"}]}]} || App <- relx_plugin_apps_extra()]. + ] ++ snabbkaffe_overrides(). %% Temporary workaround for a rebar3 erl_opts duplication %% bug. Ideally, we want to set this define globally @@ -63,13 +36,10 @@ snabbkaffe_overrides() -> Apps = [snabbkaffe, ekka, mria], [{add, App, [{erl_opts, [{d, snk_kind, msg}]}]} || App <- Apps]. -config(HasElixir) -> +config() -> [ {cover_enabled, is_cover_enabled()} , {profiles, profiles()} - , {plugins, plugins(HasElixir)} - | [ {provider_hooks, [ {pre, [{compile, {mix, find_elixir_libs}}]} - , {post, [{compile, {mix, consolidate_protocols}}]} - ]} || HasElixir ] + , {plugins, plugins()} ]. is_cover_enabled() -> @@ -107,13 +77,12 @@ project_app_dirs(Edition) -> false -> [] end. -plugins(HasElixir) -> +plugins() -> [ {relup_helper,{git,"https://github.com/emqx/relup_helper", {tag, "2.0.0"}}} , {er_coap_client, {git, "https://github.com/emqx/er_coap_client", {tag, "v1.0.4"}}} %% emqx main project does not require port-compiler %% pin at root level for deterministic , {pc, {git, "https://github.com/emqx/port_compiler.git", {tag, "v1.11.1"}}} - | [ {rebar_mix, "0.5.1"} || HasElixir ] ] %% test plugins are concatenated to default profile plugins %% otherwise rebar3 test profile runs are super slow @@ -333,8 +302,7 @@ is_app(Name) -> relx_plugin_apps(ReleaseType, Edition) -> relx_plugin_apps_per_rel(ReleaseType) - ++ relx_plugin_apps_enterprise(Edition) - ++ relx_plugin_apps_extra(). + ++ relx_plugin_apps_enterprise(Edition). relx_plugin_apps_per_rel(cloud) -> []; @@ -346,10 +314,6 @@ relx_plugin_apps_enterprise(ee) -> filelib:is_dir(filename:join(["lib-ee", A]))]; relx_plugin_apps_enterprise(ce) -> []. -relx_plugin_apps_extra() -> - {_HasElixir, ExtraDeps} = extra_deps(), - [Plugin || {Plugin, _} <- ExtraDeps]. - relx_overlay(ReleaseType, Edition) -> [ {mkdir, "log/"} , {mkdir, "data/"} diff --git a/scripts/find-apps.sh b/scripts/find-apps.sh index 003ffbc5e..7d7e5d33c 100755 --- a/scripts/find-apps.sh +++ b/scripts/find-apps.sh @@ -12,8 +12,3 @@ find_app() { find_app 'apps' find_app 'lib-ee' - -## find directories in lib-extra -find_app 'lib-extra' -## find symlinks in lib-extra -find 'lib-extra' -mindepth 1 -maxdepth 1 -type l -exec test -e {} \; -print