Skip to content

To be merged for 7.2 MTA-3848: MTA flags are missing in the documentation #75

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

Open
wants to merge 26 commits into
base: main
Choose a base branch
from
Open

To be merged for 7.2 MTA-3848: MTA flags are missing in the documentation #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
13575bd
MTA-4161: MTA flags are missing in the documentation
anarnold97 Nov 3, 2024
e6d8cc8
Update
anarnold97 Nov 3, 2024
ad086c1
Update master.adoc
anarnold97 Nov 3, 2024
e180b1c
Update
anarnold97 Nov 4, 2024
5d5450e
Update
anarnold97 Nov 4, 2024
a3738b8
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
3ced2db
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
29f737f
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
7bbfa0f
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
8d61cd0
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
9e66d1f
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
114489e
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
8bd18f2
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
959ac75
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
dfa0ecf
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
8ac4819
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 6, 2024
550896b
Update mta-cli-args.adoc
anarnold97 Nov 11, 2024
23a8e38
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 11, 2024
d3abf0b
update
anarnold97 Nov 14, 2024
2eebab5
Update mta-cli-args.adoc
anarnold97 Nov 14, 2024
369bbf2
Update mta-cli-args.adoc
anarnold97 Nov 14, 2024
235eeb6
Update mta-cli-args.adoc
anarnold97 Nov 14, 2024
805abf0
Update mta-cli-args.adoc
anarnold97 Nov 14, 2024
16191b7
Update docs/topics/mta-cli-args.adoc
anarnold97 Nov 18, 2024
20f7cf9
Update mta-cli-args.adoc
anarnold97 Nov 18, 2024
48ee6f4
To be merged for 7.2 MTA-4161: Missing flags in the docs
anarnold97 Nov 27, 2024
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
3 changes: 1 addition & 2 deletions docs/cli-guide/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,5 +135,4 @@ include::topics/important-links.adoc[leveloffset=+3]
// **********************************
include::topics/templates/revision-info.adoc[]



:!cli-guide:
231 changes: 117 additions & 114 deletions docs/topics/mta-cli-args.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,137 +2,162 @@
//
// * docs/cli-guide/master.adoc

:_mod-docs-content-type: REFERENCE
:_content-type: REFERENCE
[id="cli-args_{context}"]
= About {ProductShortName} command-line arguments

The following is a detailed description of the available {ProductShortName} command line arguments.

[NOTE]
====
To run the {ProductShortName} command, for example when executing from a script, you must use the following arguments:
To run the {ProductShortName} command without prompting, for example when executing from a script, you must use the following arguments:

* `--overwrite`
* `--input`
* `--target`
====


.{ProductShortName} CLI arguments
[cols="40%,60%a",options="header",]
[%collapsible]
====
[width="100%",cols="30%,30%,65%",options="header",]
|====
|Argument |Description
|--analyze-known-libraries | Flag to analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code.
|Command |Type|Description

[NOTE]
====
This option might result in a longer execution time and a large number of migration issues being reported.
====
a|`--analyze-known-libraries`
|
|Flag to analyze known open-source libraries.

|--help |Display the {ProductShortName} help message.
|--input |A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required.
| --list-sources
| list rules for available migration sources
|--list-sources | Flag to list all available source technologies.
|--list-targets| Flag to list all available target technologies.
|--output |Specify the path to the directory to output the report information generated by {ProductShortName}.
a|`--bulk`
|
a|Flag for running multiple analyze commands in bulk, which result in a combined static report.

[IMPORTANT]
====
Do not overwrite a report output directory that contains important information.
====
| --rules stringArray | Filename or directory containing rule files
| --source |A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources.
|--target |A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. Use the `--list-targets` argument to list all available targets.
|====
|`--context-lines`
|Integer
|Flag to define the number of lines of source code to include in the output for each incident (default: `100`).

[id="cli-input-argument_{context}"]
== Specifying the input
a|`-d`, `--dependency-folders`
|String Array
|Flag for the directory for dependencies.

A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required.
a|`--enable-default-rulesets`
|Boolean
a|Flag to run default rulesets with analysis (default: `true`).

.Usage
[source,options="nowrap",subs="attributes+"]
----
--input <INPUT_ARCHIVE_OR_DIRECTORY> [...]
----
a|`-h`, `--help`
|
|Flag to output help for analyze

[id="cli-input-file-type-arguments_{context}"]
== Analyze application source code
a|`--http-proxy`
| String
| Flag for Hyper Text Transfer Protocol (HTTP) proxy string URL

Usage: `{mta-cli} analyze [flags]`
a|`--https-proxy`
| String
| Flag for Hypertext Transfer Protocol Secure (HTTPS) proxy string URL

The following flags are available:
a|`--incident-selector`
|String
a|Flag to select incidents based on custom variables, for example, `!package=io.konveyor.demo.config-utils`

.{ProductShortName} Analyze application
[cols="40%,60%a",options="header",]
|====
|Flag |Description
a|`-i`, `--input`
|String
a|Flag for the path to application source code or a binary. For more details, see xref:cli-input-argument_cli-guide[Specifying the input].

| --analyze-known-libraries
| analyze known open source libraries
a|`--jaeger-endpoint`
|String
|Flag for the jaeger endpoint to collect traces.

| -h, --help
| help for analyze
a|`--json-output`
|
a|Flag to create analysis and dependency output as JSON.

| -i, --input string
| path to application source code or a binary
a|`-l`, `--label-selector`
|String
|Flag to run rules based on a specified label selector expression.

| --json-output
| create analysis and dependency output as JSON
a|`--list-providers`
|
|Flag to list available supported providers.

| --list-sources
| list rules for available migration sources
a|`--list-sources`
|
a|Flag to list rules for available migration sources.

| --list-targets
| list rules for available migration targets
a|`--list-targets`
|
|Flag to list rules for available migration targets.

| -l, --label-selector string
| run rules based on specified label selector expression
a|`--maven-settings`
|string
|Flag path to a custom Maven settings file to use

| --maven-settings string
| path to a custom maven settings file to use
a|`-m`, `--mode`
|String
a|Flag for analysis mode, this must be one of `full`, for `source` and `dependencies`, or `source-only` (default `full`).

| --overwrite
| overwrite output directory
a|`--no-proxy`
|String
|Flag to excluded URLs from passing through any proxy (relevant only with proxy)

| --skip-static-report
| do not generate static report
a|`-o`, `--output`
|String
|Flag for the path to the directory for analysis output. For more details, see xref:cli-output-argument_cli-guide[Specifying the output directory].

| -m, --mode string
| analysis mode" `full` (default) or `source-only`
a|`--override-provider-settings`
|String
|Flag to override the provider settings. The analysis pod runs on the host network, and no providers are started.

| -o, --output string | path to the directory for analysis output
a|`--overwrite`
|
|Flag to overwrite the output directory. If you do not specify this argument and the `--output` directory exists, you are prompted to choose whether to overwrite the contents.

| --rules stringArray | filename or directory containing rule files
a|`--provider`
|String Array
|Flag to specify which provider or providers to run.

| --skip-static-report
| do not generate static report
a|`--rules`
|String Array
a|Flag to specify the filename or directory containing rule files. Use multiple times for additional rules, for example, `--rules --rules …`.

| -s, --source string
| source technology to consider for analysis. To specify multiple sources, repeat the parameter: --source <source_1> --source <source_2> etc.
a|`--run-local`
|
|Local flag to run analysis directly on local system without containers, for Java and Maven (default `full`). This flag can be disabled with `--run-local=false`.

| -t, --target string
| target technology to consider for analysis. To specify multiple targets, repeat the parameter: --target <target_1> --target <target_2> etc.
|====
a|`--skip-static-report`
|
|Flag to not generate static report.

[id="cli-input-file-type-arguments-global-flags_{context}"]
=== Global flags
a|`-s`, `--source`
|String Array
a|Flag for the source technology to consider for analysis. Use multiple times for additional sources, for example, `--source --source …`. For more details, see xref:cli-source-argument_cli-guide[Setting the source technology].

.{ProductShortName} Analyze application
[cols="40%,60%a",options="header",]
a|`-t`, `--target`
|String Array
a|Flag for the target technology to consider for analysis. Use multiple times for additional targets, for example, `--target --target …`. For more details, see xref:cli-target-argument_cli-guide[Setting the target technology].
|====
====

|Flag
|Description
[id="cli-input-argument_{context}"]
== Specifying the input

| --log-level uint32
| log level (default 4)
A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required.

| --no-cleanup
| do not clean up temporary resources
|====
.Usage
[source,options="nowrap",subs="attributes+"]
----
--input <INPUT_ARCHIVE_OR_DIRECTORY> [...]
----

Depending on whether the input file type provided to the `--input` argument is a file or directory, it will be evaluated as follows depending on the additional arguments provided.

Directory::
+
* `--sourceMode`: The directory is evaluated as a single application.

File::
+
* `--sourceMode`: The file is evaluated as a compressed project.


[id="cli-output-argument_{context}"]
Expand All @@ -146,39 +171,40 @@ Specify the path to the directory to output the report information generated by
--output <OUTPUT_REPORT_DIRECTORY>
----

* The `--output` argument is mandatory. If omitted, an error is returned:
* If omitted, the report will be generated in an `<INPUT_ARCHIVE_OR_DIRECTORY>.report` directory.
* If the output directory exists, you will be prompted with the following question with a default answer of `N`:
+
[source,options="nowrap",subs="attributes+"]
----
Error: required flag(s) "output" not set
Overwrite all contents of "/home/username/<OUTPUT_REPORT_DIRECTORY>" (anything already in the directory will be deleted)? [y,N]
----

However, if you specify the `--overwrite` argument, {ProductShortName} will proceed to delete and re-create the directory. See the description of this argument for more information.
However, if you specify the `--overwrite` argument, {ProductShortName} will proceed to delete and recreate the directory. See the description of this argument for more information.

[id="cli-source-argument_{context}"]
== Setting the source technology

A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--list-sources` argument to list all available sources.
A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. You can use this argument, in conjunction with the `--target` argument, to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources.

.Usage
[source,options="nowrap",subs="attributes+"]
----
--source <SOURCE_1> <SOURCE_2>
----

The `--source` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--source eap5`.
The `--source` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions, for example, `--source eap:5`.

[WARNING]
====
When migrating to JBoss EAP, be sure to specify the version, for example, `eap6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.
When migrating to JBoss EAP, be sure to specify the version, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.

See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version.
====

[id="cli-target-argument_{context}"]
== Setting the target technology

A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. If you do not provide a target, mta-cli analyzes the input based on the source and discovery rules. Use the `--list-targets` argument to list all available targets.
A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. You can use this argument, in conjunction with the `--source` argument, to determine which rulesets are used. If you do not specify this option, you are prompted to select a target. Use the `--listTargetTechnologies` argument to list all available targets.

.Usage
[source,options="nowrap",subs="attributes+"]
Expand All @@ -187,27 +213,4 @@ A space-delimited list of one or more target technologies, servers, platforms, o
----


The `--target` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--target eap7`.

[WARNING]
====
When migrating to JBoss EAP, be sure to specify the version in the target, for example, `eap6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.

See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version.
====

////
[id="cli-packages-argument_{context}"]
== Selecting packages

A space-delimited list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument.

.Usage
[source,options="nowrap",subs="attributes+"]
----
----

* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The `<PACKAGE_N>` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use `--packages com.mycustomapp com.myotherapp` argument on the command line.
* While you can provide package names for standard Java EE third party software such as `org.apache`, it is usually best not to include them as they should not impact the migration effort.

////
The `--target` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions, for example, `--target eap:7`.
1 change: 1 addition & 0 deletions docs/topics/mta-review-reports.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,3 +299,4 @@ This report provides the list of rules that ran when running the {ProductShortNa

.Rule providers execution overview
image::3-13-rule-providers-execution-overview.png[Rule Provider Execution Overview]
////