Skip to content
This repository has been archived by the owner on Dec 20, 2022. It is now read-only.

Commit

Permalink
Merge pull request #67 from pfistererm/mp_quickstart_doc_rework
Browse files Browse the repository at this point in the history 
Quickstart documentation rework
  • Loading branch information
@davu-all
davu-all authored Nov 7, 2019
2 parents a877afe + 36cefec commit 6b60e21
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 48 deletions.
106 changes: 61 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,63 +26,79 @@ For detail information, see the [full documentation](org.aposin.licensescout.doc

* Maven 3 installation

### Usage

Declare the Plugin and executions in the `pom.xml`:
### Run the quickstart example

```xml
<plugins>
<plugin>
<groupId>org.aposin.licensescout</groupId>
<artifactId>licensescout-maven-plugin</artifactId>
<version>1.1.4</version>
<executions>
<execution>
<id>find-licenses</id>
<phase>verify</phase>
<goals>
<goal>scanJava</goal>
</goals>
<configuration>
<scanDirectory>${project.build.directory}/products/my.product/win32/win32/x86/plugins/</scanDirectory>
<outputDirectory>${licensescout.outputDirectory}</outputDirectory>
<outputs>
<output>
<type>TXT</type>
<filename>${licensescout.outputFilename.txt}</filename>
<url>${licensereport.url.txt}</url>
</output>
</outputs>
<licensesFilename>${licensescout-configuration.dir}/licenses.xml</licensesFilename>
<providersFilename>${licensescout-configuration.dir}/providers.xml</providersFilename>
<noticesFilename>${licensescout-configuration.dir}/notices.xml</noticesFilename>
<checkedArchivesFilename>${licensescout-configuration.dir}/checkedarchives.csv</checkedArchivesFilename>
<licenseUrlMappingsFilename>${licensescout-configuration.dir}/urlmappings.csv</licenseUrlMappingsFilename>
<licenseNameMappingsFilename>${licensescout-configuration.dir}/namemappings.csv</licenseNameMappingsFilename>
<globalFiltersFilename>${licensescout-configuration.dir}/globalfilters.csv</globalFiltersFilename>
<filteredVendorNamesFilename>${licensescout-configuration.dir}/filteredvendornames.csv</filteredVendorNamesFilename>
</configuration>
</execution>
</executions>

</plugin>
</plugin>
To build and run LicenseScout on itself in this repository:

```bash
cd org.aposin.licensescout.quickstart
mvn clean install
```

This does:
* Compiles the LicenseScout Maven plug-in
* Creates a LicenseScout configuration bundle
* Runs the LicenseScout on its own dependencies and creates license reports for it

The reports are written to the directory `org.aposin.licensescout.licensereport/target`.

:information_source: For further information about how to configure the Plugin, please see the [full documentation](org.aposin.licensescout.core/doc/documentation.adoc).

As an example output, the [NOTICE.txt](NOTICE.txt) in this repository is the result of LiceseScout running on itself.

### Building
### Next steps

To build and run LicenseScout on itself in this repository:
#### Run LicenseScout on your own project

```bash
cd org.aposin.licensescout.quickstart
mvn clean install
Have a look at the `pom.xml` in `org.aposin.licensescout.licensereport`. It contains a typical configuration of how the LicenseScout is applied to a project.

You may want to start by re-using this project and just alter the parameter `scanDirectory` (Note: the value may also be an absolute path that points anywhere in the file system).

Alternatively, you can copy out the plugin configurations and take them over to your own project's POM.

#### Create a project specific configuration

The quickstart example you just executed uses a minimal configuration
that is just sufficient to run the LicenseScout on its own dependencies.

For you own project, you will need to maintain a configuration that is specific to your project. Take the project `org.aposin.licensescout.configuration.sample` as a starting point by creating a copy of it. If you cange the name of the project (recommended!) make sure you also adapt the group and artifact IDs that are used as configuration in the licensescout run (in `org.aposin.licensescout.licensereport/pom.xml`):

```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
...
<configuration>
<artifactItems>
<artifactItem>
<groupId>your.new.groupId</groupId>
<artifactId>your.new.artifactId</artifactId>
<version>${org.aposin.licensescout.configuration.version}</version>
<classifier>configuration</classifier>
...
</artifactItem>
</artifactItems>
...
</configuration>
</execution>
</executions>
</plugin>
```

The reports are written to the directory `org.aposin.licensescout.licensereport/target`.
Then, start adding the configurations you need:
* License definitions
* License notices
* Vendor names (for filtering out own artifacts)
* License name and URL mappings
* Exceptions for certain artifacts (`checkedarchives.csv`)
* Provider definitions

See also the full documentation: it describes the format of the configuration files and how their information is processed.

You may also want to create a customized version of the templates used for the license reports.

## Contributing

Expand Down
6 changes: 3 additions & 3 deletions org.aposin.licensescout.documentation/doc/documentation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ LicenseScout is configured as a Maven plugin. Below you can see a typical config
<plugin>
<groupId>org.aposin.licensescout</groupId>
<artifactId>licensescout-maven-plugin</artifactId>
<version>1.1.4</version>
<version>1.3.1-SNAPSHOT</version>
<executions>
<execution>
<id>find-licenses</id>
Expand Down Expand Up @@ -342,7 +342,7 @@ Example:
</configuration>
----

It is recommended to configure the values for `username` and `password` via `settings.xml`.
It is recommended to configure the values for `username` and `password` via `settings.xml` so that they do not appear in the normal project POMs that are under version control and are easily visible to everybody.


=== Configuration files
Expand Down Expand Up @@ -656,7 +656,7 @@ In builds that use this configuration project it is downloaded and unpacked to a
<artifactItem>
<groupId>org.aposin.licensescout</groupId>
<artifactId>org.aposin.licensescout.configuration.sample</artifactId>
<version>1.0.0-SNAPSHOT</version>
<version>1.3.1-SNAPSHOT</version>
<classifier>configuration</classifier>
<type>zip</type>
<overWrite>true</overWrite>
Expand Down

0 comments on commit 6b60e21

Please sign in to comment.