Skip to content

Latest commit

 

History

History
148 lines (108 loc) · 5.94 KB

USAGE.adoc

File metadata and controls

148 lines (108 loc) · 5.94 KB
Raw

How to use this tool

Direct usage

mvn clean compile exec:java -Dexec.args="args go here"

Dockerfile

A Dockerfile is provided for ease of running without necessary environment (JDK, Maven, etc.)

Simply do:

docker build -t jenkins/usage-in-plugins .

# Run it
docker run -ti \
           -v maven-repo:/root/.m2/repository \
           -v downloaded-plugins:/project/work \
           -v $PWD/output:/project/output \
              jenkins/usage-in-plugins
...

# Run it on a subset of classes (with all sample output)
$ cat add.txt
javax/xml/bind/DatatypeConverterImpl
javax/xml/bind/DatatypeConverter
$ docker run -ti \
           -v maven-repo:/root/.m2/repository \
           -v downloaded-plugins:/project/work \
           -v $PWD/output:/project/output \
           -v $PWD/add.txt:/project/additional-classes.txt:ro \
              jenkins/usage-in-plugins -C additional-classes.txt -i
Downloaded update-center.json
All files are up to date (1590 plugins)
Analyzing deprecated api in Jenkins
additional-classes.txt found, adding 2 classes
        adding javax/xml/bind/DatatypeConverterImpl
        adding javax/xml/bind/DatatypeConverter
Analyzing deprecated usage in plugins
.......... .......... .......... .......... ..........
.......... .......... .......... .......... ..........
.......... .......... .......... .......... ..........
.........Writing output/usage-by-plugin.json
Writing output/usage-by-plugin.html
Writing output/deprecated-and-unused.json
Writing output/deprecated-and-unused.html
Writing output/usage-by-api.json
Writing output/usage-by-api.html

Finding Usage of Classes, Methods and Fields

The command line flag -M filename.txt or --additionalMethods filename.txt allows you to search for specific methods. Use the additional flag -i or --onlyIncludeSpecified to only show usage of specified classes, methods, and fields. For example, to find usage of hudson.util.Secret.toString, include the following line in the specified file:

hudson.util.Secret#toString

Specify class names in their fully qualified form (i.e., inner classes should be referenced via Outer$Inner rather than by their canonical names). Specify method names after the hash. You cannot specify distinct method signatures. All variants are included in reports.

For Fields

The command line flag -F filename.txt or --additionalFields filename.txt allows you to find specific field usages. The syntax here is the same as for specifying method names.

Example:

jenkins.model.Jenkins#ADMINISTER

For Classes

The command line flag -C filename.txt or --additionalClasses filename.txt allows you to find specific classes usages. The syntax here is the same as for specifying method names.

Example:

hudson.model.Hudson

Finding Usage by Package

By using just a package name instead of the fully qualified class name in "Class", "Method" or "Field" options, this searches for classes that start with the same specified package. For example, the following snippet would search for usage of methods or fields named toString in any classes inside the hudson.util package or its descendants.

By default, the package name is check for exactness, but you can customize it by adding * at the beginning, the end or both, to have a startsWith, endsWith or contains behavior respectively.

hudson.util.*#toString

Note the trailing .* before the # separator which makes the search more specific to hudson.util rather than also including the hypothetical package hudson.utils or hudson.utility.

Limit scope of plugins

By default all the plugins included in the update-center JSON will be analysed. You can use the arguments -l filename.txt or --limitPlugins filename.txt to limit which plugins you can want to analyse. The file must contain the artifact ID of the plugins, one per line.

Additional information

Multiple entries can be put in the file related to those options, one per line. The lines are trimmed and if one starts with a #, it’s considered as a comment, and thus ignored. The "class full name" can be written with . or with / without incidence.

Configuring Parallelism

The default parallelism settings will allow up to 4x the number of available CPUs downloads at a time. This can be overridden by the -D N or --downloadConcurrent=N option for some number N.

Including libraries from plugins

The plugins often include libraries in addition to their direct code. By default they are not included. This can be overridden by the -p or --includePluginLibs=true.

Configuring Recursion

By default the recursion is disabled. You can enable it by using -r or --recursive. The level of depth used as a boundary for the recursion is managed by the argument --recursiveMaxDepth MAX_DEPTH, with a default value to 5.

There is a builtin anti-loop mechanism to prevent methods calling a method already in the call hierarchy.

The reports containing "recursive" in their name will contain information only in this case this option is enabled.

Advanced search related to Jenkins Core

When you search for something, the tool will look at the plugins, not including Jenkins Core. With --includeCore, you can also scan the Core code for the desired pattern. This can be extended to also look for Core libraries, like for plugins, with --includeCoreLibs. As the tool is moving to a more broader search tool capacities compared to the original "deprecation search", there is an option to ignore the deprecated calls, by passing --onlyIncludeSpecified.

Development utilities

The default behavior is to download the configure Update Center metadata and then compared the local cache (using checksum) in order to determine which cores/plugins need to be downloaded. If you want to avoid downloading the latest updates but just using what you have on disk (esp. useful during debugging session), you can use the argument --skipDownloads.