Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance JBang Documentation with Configuration and Qute Template #41744

Merged
merged 1 commit into from
Jul 7, 2024
Merged

Enhance JBang Documentation with Configuration and Qute Template #41744

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 35 additions & 7 deletions docs/src/main/asciidoc/scripting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -373,22 +373,33 @@

With that in place running `jbang quarkusapp.java` will log and render as expected.

== Configuring Application

Check warning on line 376 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Configuring Application'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Configuring Application'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 376, "column": 4}}}, "severity": "INFO"}

You can use `//Q:CONFIG <property>=<value>` to set up static configuration for your application.
To configure the application you can use the `application.properties` file as usual, but you need to _add_ it to the script:

Check warning on line 378 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 378, "column": 76}}}, "severity": "INFO"}

Check warning on line 378 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 378, "column": 94}}}, "severity": "INFO"}

I.e. if you wanted to add the `smallrye-openapi` and `swagger-ui` extensions and have the Swagger UI always show up you would add the following:
[source,java]
----
//FILES application.properties

[source,java,subs=attributes+]
// ...
@ConfigProperty(name = "prefix", defaultValue = "WG -")
String prefix;
----

This will make the `application.properties` file available to the script, and process the configuration as usual.

Check warning on line 389 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 389, "column": 93}}}, "severity": "INFO"}

Check warning on line 389 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 389, "column": 105}}}, "severity": "INFO"}

You can also use the `application.yaml` file.
For this, you need to _add_ it to the `application.yaml` file to the script and include the `quarkus-config-yaml` dependency:

[source,java]
----
//DEPS io.quarkus:quarkus-smallrye-openapi:{quarkus-version}
//DEPS io.quarkus:quarkus-swagger-ui:{quarkus-version}
//Q:CONFIG quarkus.swagger-ui.always-include=true
//DEPS io.quarkus:quarkus-config-yaml
//FILES application.yaml
----

Now during build the `quarkus.swagger-ui.always-include` will be generated into the resulting jar and `http://0.0.0.0:8080/q/swagger-ui` will be available when run.
NOTE: The path to the `application.properties` and `application.yaml` files are relative to the script file.

== Running as a native application

Check warning on line 402 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 402, "column": 12}}}, "severity": "INFO"}

If you have the `native-image` binary installed and `GRAALVM_HOME` set, or a container runtime (e.g., podman or docker) installed on Linux, you can get the native executable built and run using `jbang --native quarkusapp.java`:

Expand Down Expand Up @@ -440,6 +451,23 @@
2023-03-22 09:38:45,450 INFO [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
----

=== Using Qute

You can use the xref:./qute.adoc[Qute templating engine] in your JBang script by adding the `quarkus-qute` dependency.

Check warning on line 456 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 456, "column": 34}}}, "severity": "INFO"}
You also need to include the `templates` directory in the script:
[source,java]
----
//DEPS io.quarkus:quarkus-qute
//FILES templates/=templates/*

// ...

@Inject
Template template; // Locate and load the `templates/template.html` file
----

If your `templates` directory includes sub-directories, use `templates/=templates/**/*` instead.

=== Conclusion

If you want to get started with Quarkus or write something quickly, Quarkus Scripting with jbang lets you do that. No Maven, no Gradle - just a Java file. In this guide we outlined the very basics on using Quarkus with JBang; if you want to learn more about what JBang can do, go see https://jbang.dev.

Check warning on line 473 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'jbang'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'jbang'?", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 473, "column": 92}}}, "severity": "WARNING"}

Check warning on line 473 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 473, "column": 200}}}, "severity": "INFO"}