This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit fd1646a90a53f1f6f26447335108778db13aacb1
Author: Nicola Ferraro <ni.ferr...@gmail.com>
AuthorDate: Fri May 8 12:41:12 2020 +0200
Fix #1449: document modeline and CLI
---
docs/modules/ROOT/nav-end.adoc | 2 -
docs/modules/ROOT/nav.adoc | 4 ++
docs/modules/ROOT/pages/cli/cli.adoc | 54 +++++++++++++++++
docs/modules/ROOT/pages/cli/modeline.adoc | 98 +++++++++++++++++++++++++++++++
pkg/cmd/run.go | 2 +-
5 files changed, 157 insertions(+), 3 deletions(-)
diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc
index ff8f435..bfd2ea1 100644
--- a/docs/modules/ROOT/nav-end.adoc
+++ b/docs/modules/ROOT/nav-end.adoc
@@ -1,4 +1,2 @@
-* xref:tutorials/tutorials.adoc[Tutorials]
-** xref:tutorials/tekton/tekton.adoc[Tekton Pipelines]
* xref:uninstalling.adoc[Uninstalling]
* xref:developers.adoc[Contributing to Camel K]
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 6d7dde0..9754790 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -9,6 +9,10 @@
*** xref:installation/registry/gcr.adoc[Gcr.io]
* xref:running/running.adoc[Running]
** xref:running/dev-mode.adoc[Dev Mode]
+* xref:tutorials/tutorials.adoc[Tutorials]
+** xref:tutorials/tekton/tekton.adoc[Tekton Pipelines]
+* xref:cli/cli.adoc[CLI]
+** xref:cli/modeline.adoc[Modeline]
* xref:configuration/configuration.adoc[Configuration]
** xref:configuration/components.adoc[Components]
** xref:configuration/logging.adoc[Logging]
diff --git a/docs/modules/ROOT/pages/cli/cli.adoc
b/docs/modules/ROOT/pages/cli/cli.adoc
new file mode 100644
index 0000000..a388d17
--- /dev/null
+++ b/docs/modules/ROOT/pages/cli/cli.adoc
@@ -0,0 +1,54 @@
+= Camel K CLI (kamel)
+
+The Camel K command line interface (kamel) is the main entry point for running
integrations on a Kubernetes cluster.
+
+Releases of the Camel K CLI are available on:
+
+- Apache Mirrors (official): https://downloads.apache.org/camel/camel-k/
+- Github Releases: https://github.com/apache/camel-k/releases
+- Homebrew (Mac and Linux): https://formulae.brew.sh/formula/kamel
+
+== Available Commands
+
+Some of the most used commands are:
+
+.Useful Commands
+|===
+|Name |Description |Example
+
+|help
+|Obtain the full list of available commands
+|`kamel help`
+
+|init
+|Initialize empty Camel K files
+|`kamel init Routes.java`
+
+|run
+|Run an integration on Kubernetes
+|`kamel run Routes.java`
+
+|get
+|Get integrations deployed on Kubernetes
+|`kamel get`
+
+|describe
+|Get detailed information on a resource
+|`kamel describe integration routes`
+
+|log
+|Print the logs of a running integration
+|`kamel log routes`
+
+|delete
+|Delete integrations deployed on Kubernetes
+|`kamel delete routes`
+
+|===
+
+The list above is not the full list of available commands. You can run `kamel
help` to obtain the full list.
+
+== Modeline
+
+Some command options in the CLI can be also specified as modeline in the
source file, take a look at the xref:cli/modeline.adoc[Modeline section]
+for more information.
diff --git a/docs/modules/ROOT/pages/cli/modeline.adoc
b/docs/modules/ROOT/pages/cli/modeline.adoc
new file mode 100644
index 0000000..9f58304
--- /dev/null
+++ b/docs/modules/ROOT/pages/cli/modeline.adoc
@@ -0,0 +1,98 @@
+= Camel K Modeline
+
+Integration files can contain modeline hooks that allow to customize the way
integrations are executed via command line.
+
+For example, take the following integration file:
+
+.Hello.java
+----
+// camel-k: dependency=mvn:org.my:application:1.0 // <1>
+
+import org.apache.camel.builder.RouteBuilder;
+
+public class Hello extends RouteBuilder {
+ @Override
+ public void configure() throws Exception {
+
+ from("timer:java?period=1000")
+ .bean(org.my.BusinessLogic) // <2>
+ .log("${body}");
+
+ }
+}
+----
+<1> Modeline import of Maven library
+<2> Usage of a business logic class from the external library
+
+When the integration code above is executed using the `kamel run` CLI command,
the modeline options declared in the file are appended to
+the list of arguments that are passed to the command.
+
+The `kamel` CLI will alert you, printing the full command in the shell:
+
+----
+$ kamel run Hello.java
+Modeline options have been loaded from source files
+Full command: kamel run Hello.java --dependency mvn:org.my:application:1.0
+...
+----
+
+Multiple options, even of the same type, can be specified for an integration.
For example
+the following modeline options make sure that the integration runs on the
Quarkus runtime and enable the 3scale exposure.
+
+.QuarkusRest.java
+----
+// camel-k: trait=quarkus.enabled=true trait=3scale.enabled=true // <1>
+
+import org.apache.camel.builder.RouteBuilder;
+
+public class QuarkusRest extends RouteBuilder {
+ @Override
+ public void configure() throws Exception {
+
+ rest().get("/")
+ .route()
+ .setBody().constant("Hello");
+
+ }
+}
+----
+<1> Enable both the Quarkus and 3scale traits, to run the integration on
Quarkus and expose the routes via 3scale
+
+All options that are available for the `kamel run` command can be specified as
modeline options.
+The following is a partial list of useful options:
+
+.Useful Modeline Options
+|===
+|Option | Description
+
+|dependency
+|An external library that should be included. E.g. for Maven dependencies
"dependency=mvn:org.my/app:1.0"
+
+|env
+|Set an environment variable in the integration container. E.g
"env=MY_VAR=my-value"
+
+|label
+|Add a label to the integration. E.g. "label=my.company=hello"
+
+|name
+|The integration name
+
+|open-api
+|Add an OpenAPI v2 spec (file path)
+
+|profile
+|Trait profile used for deployment
+
+|property
+|Add a camel property
+
+|property-file
+|Bind a property file to the integration. E.g.
"property-file=integration.properties"
+
+|resource
+|Add a resource
+
+|trait
+|Configure a trait. E.g. "trait=service.enabled=false"
+
+|===
diff --git a/pkg/cmd/run.go b/pkg/cmd/run.go
index 66e3a88..c5faea6 100644
--- a/pkg/cmd/run.go
+++ b/pkg/cmd/run.go
@@ -72,7 +72,7 @@ func newCmdRun(rootCmdOptions *RootCmdOptions)
(*cobra.Command, *runCmdOptions)
}
cmd.Flags().String("name", "", "The integration name")
- cmd.Flags().StringArrayP("dependency", "d", nil, "The integration
dependency")
+ cmd.Flags().StringArrayP("dependency", "d", nil, "An external library
that should be included. E.g. for Maven dependencies \"mvn:org.my/app:1.0\"")
cmd.Flags().BoolP("wait", "w", false, "Waits for the integration to be
running")
cmd.Flags().StringP("kit", "k", "", "The kit used to run the
integration")
cmd.Flags().StringArrayP("property", "p", nil, "Add a camel property")
