MTA-2204-Changes-needed-for-mta-cli-docs

docs/cli-guide/master.adoc

@@ -53,25 +53,25 @@ include::topics/available-openrewrite-recipes.adoc[leveloffset=+4]
 include::topics/access-report.adoc[leveloffset=+2]
 
 // Review the Reports
-include::topics/review-reports.adoc[leveloffset=+1]
+include::topics/mta-review-reports.adoc[leveloffset=+1]
 
 // Export the Report in CSV Format
-include::topics/csv-export.adoc[leveloffset=+1]
+// include::topics/csv-export.adoc[leveloffset=+1]
 
 // Mavenize Your Application
-include::topics/mavenize.adoc[leveloffset=+1]
+// include::topics/mavenize.adoc[leveloffset=+1]
 
 // Optimize {ProductShortName} Performance
-include::topics/optimize-performance.adoc[leveloffset=+1]
+include::topics/mta-optimize-performance.adoc[leveloffset=+1]
 
 // Configure {ProductShortName} to Exclude Files and Packages
-include::topics/exclude-files-and-packages.adoc[leveloffset=+2]
+// include::topics/mta-exclude-files-and-packages.adoc[leveloffset=+2]
 
 [appendix]
 == Reference material
 
 // {ProductShortName} Command-line Arguments
-include::topics/cli-args.adoc[leveloffset=+2]
+include::topics/mta-cli-args.adoc[leveloffset=+2]
 
 // Added in 4.3.0: list of supported Tech Tags
 include::topics/tech-tags.adoc[leveloffset=+2]

docs/topics/mta-cli-args.adoc

@@ -0,0 +1,213 @@
+// Module included in the following assemblies:
+//
+// * docs/cli-guide/master.adoc
+
+:_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:
+
+* `--overwrite`
+* `--input`
+* `--target`
+====
+
+
+.{ProductShortName} CLI arguments
+[cols="40%,60%a",options="header",]
+|====
+|Argument |Description
+|--analyze-known-libraries | Flag to analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code.
+
+[NOTE]
+====
+This option may result in a longer execution time and a large number of migration issues being reported.
+====
+
+|--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}.
+
+[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.
+|====
+
+[id="cli-input-argument_{context}"]
+== Specifying the 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.
+
+.Usage
+[source,options="nowrap",subs="attributes+"]
+----
+--input <INPUT_ARCHIVE_OR_DIRECTORY> [...]
+----
+
+[id="cli-input-file-type-arguments_{context}"]
+== Analyze application source code
+
+Usage: `{mta-cli} analyze [flags]`
+
+The following flags are available:
+
+.{ProductShortName} Analyze application
+[cols="40%,60%a",options="header",]
+|====
+|Flag |Description
+
+| --analyze-known-libraries
+|  analyze known open-source libraries
+
+| -h, --help
+| help for analyze
+
+| -i, --input string
+|  path to application source code or a binary
+
+| --json-output
+| create analysis and dependency output as json
+
+| --list-sources
+| list rules for available migration sources
+
+| --list-targets
+| list rules for available migration targets
+
+| -l, --label-selector string
+| run rules based on specified label selector expression
+
+| --maven-settings string
+| path to a custom maven settings file to use
+
+| --overwrite
+| overwrite output directory
+
+| --skip-static-report
+|  do not generate static report
+
+| -m, --mode string
+| analysis mode" `full` (default) or `source-only`
+
+| -o, --output string | path to the directory for analysis output
+
+| --rules stringArray | filename or directory containing rule files
+
+| --skip-static-report
+| do not generate static report
+
+| -s, --source string
+| source technology to consider for analysis. To specify multiple sources, repeat the parameter: --source <source_1> --source <source_2> etc.
+
+| -t, --target string
+| target technology to consider for analysis. To specify multiple targets, repeat the parameter: --target <target_1> --target <target_2> etc.
+|====
+
+[id="cli-input-file-type-arguments-global-flags_{context}"]
+=== Global flags
+
+.{ProductShortName} Analyze application
+[cols="40%,60%a",options="header",]
+|====
+
+|Flag
+|Description
+
+| --log-level uint32
+| log level (default 4)
+
+| --no-cleanup
+| do not cleanup temporary resources
+|====
+
+
+
+[id="cli-output-argument_{context}"]
+== Specifying the output directory
+
+Specify the path to the directory to output the report information generated by {ProductShortName}.
+
+.Usage
+[source,options="nowrap",subs="attributes+"]
+----
+--output <OUTPUT_REPORT_DIRECTORY>
+----
+
+* The `--output` argument is mandatory. If omitted, an error is returned:
++
+[source,options="nowrap",subs="attributes+"]
+----
+Error: required flag(s) "output" not set 
+----
+
+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.
+
+.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`.
+
+[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.
+
+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.
+
+.Usage
+[source,options="nowrap",subs="attributes+"]
+----
+--target <TARGET_1> <TARGET_2>
+----
+
+
+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 like `org.apache`, it is usually best not to include them as they should not impact the migration effort.
+
+////

docs/topics/mta-exclude-files-and-packages.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * docs/cli-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="exclude-files-and-packages_{context}"]
+= Configuring {ProductShortName} to exclude packages and files
+
+
+[id="ignored-locations_{context}"]
+== Searching locations for exclusion
+
+{ProductShortName} searches the following locations:
+
+* `~/.{LC_PSN}/ignore/`
+* `~/.windup/ignore/`
+* `<{ProductShortName}_HOME>/ignore/`
+

docs/topics/mta-optimize-performance.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * docs/cli-guide/master.adoc
+
+:_content-type: CONCEPT
+[id="optimize-performance_{context}"]
+= Optimizing {ProductShortName} performance
+
+{ProductShortName} performance depends on a number of factors, including hardware configuration, the number and types of files in the application, the size and number of applications to be evaluated, and whether the application contains source or compiled code. For example, a file that is larger than 10 MB may need a lot of time to process.
+
+In general, {ProductShortName} spends about 40% of the time decompiling classes, 40% of the time executing rules, and the remainder of the time processing other tasks and generating reports. This section describes what you can do to improve the performance of {ProductShortName}.
+
+== Deploying and running the application
+
+Try these suggestions first before upgrading hardware.
+
+* If possible, run {ProductShortName} against the source code instead of the archives. This eliminates the need to decompile additional JARs and archives.
+* Increase your ulimit when analyzing large applications. See link:https://access.redhat.com/solutions/60746[this Red Hat Knowledgebase article] for instructions on how to do this for Red Hat Enterprise Linux.
+* If you have access to a server that has better resources than your laptop or desktop machine, you may want to consider running {ProductShortName} on that server.
+
+== Upgrading hardware
+
+If the application and command-line suggestions above do not improve performance, you may need to upgrade your hardware.
+
+* If you have access to a server that has better resources than your laptop/desktop, then you may want to consider running {ProductShortName} on that server.
+* Very large applications that require decompilation have large memory requirements. 8 GB RAM is recommended. This allows 3 - 4 GB RAM for use by the JVM.
+* An upgrade from a single or dual-core to a quad-core CPU processor provides better performance.
+* Disk space and fragmentation can impact performance. A fast disk, especially a solid-state drive (SSD), with greater than 4 GB of defragmented disk space should improve performance.