Freefair Gradle Plugins

Before using FreeFair plugins, ensure your environment meets the following requirements:

• Gradle: Plugins are targeted at Gradle {gradle_version}. For version 8 and above, the Major.Minor version of the plugins matches the Major.Minor version of Gradle.
• Java: Most plugins support all Java versions supported by Gradle {gradle_version}. Note that specific plugins involving external tools (like Lombok or AJC) may have additional constraints.
• Kotlin: For most plugins, the Kotlin version is irrelevant. When plugins interface with the Kotlin Gradle plugin, they typically use the same Kotlin version as Gradle (currently {kotlin_version}).

The maven-plugin module provides several specialized plugins to bring Maven features to Gradle:

• io.freefair.war: Shortcut applying war, war-overlay, war-attach-classes, and war-archive-classes.
• io.freefair.javadocs: Shortcut applying javadoc-links and javadoc-utf-8.
• io.freefair.maven-publish-java: Applies maven-publish and java, configuring a mavenJava publication.
• io.freefair.maven-publish-war: Applies maven-publish and war, configuring a mavenWeb publication.
• io.freefair.javadoc-links: Configures Javadoc links based on classpath dependencies.
• io.freefair.javadoc-utf-8: Configures all Javadoc tasks to use UTF-8 encoding.

The io.freefair.aspectj plugin implements compile-time weaving by directly using ajc for compilation.

Key behaviors:

• It adds an aspectj directory to every SourceSet (e.g., src/main/aspectj, src/test/aspectj).
• It creates two new SourceDirectorySets per SourceSet:
  • aspectj: contains only src/<sourceSet>/aspectj.
  • allAspectj: combines aspectj with the default java SourceDirectorySet.
• The compile*Aspectj tasks use allAspectj as their source to compile both Java and AspectJ files.
• The default compile*Java tasks are disabled to avoid conflicts between ajc and javac.

If you need both ajc and javac to run independently, you must re-enable the compile*Java tasks and switch the compile*Aspectj tasks from using allAspectj to using aspectj.

There are two primary plugins available:

1. io.freefair.mjml.base: The core plugin. It adds the mjml configuration extension and handles the installation of MJML via npm.
2. io.freefair.mjml.java: An extension of the base plugin. It applies io.freefair.mjml.base and integrates the compiled HTML output directly into the Java resource processing pipeline, making the HTML files available as resources in your application.

The io.freefair.maven-plugin includes the DescriptorGeneratorTask, which is the Gradle equivalent of the Maven DescriptorGeneratorMojo.

It scans your source code for Mojo annotations (like @Mojo and @Parameter) and generates the plugin.xml descriptor. The generated descriptor is placed in build/generated/resources/maven-plugin-descriptor and is automatically added to your project's main source set resources so it is included in the final artifact.

All OkHttp tasks inherit from OkHttpRequestTask, which provides the following common properties for executing HTTP requests:

• url: The URL for the Request
• username: The username for HTTP Basic Auth
• password: The password for HTTP Basic Auth
• headers: Additional headers which will be added to the request.

Base plugins provide shared infrastructure and are applied automatically by higher-level plugins. You typically do not need to apply these directly.

Base Plugins Mapping

A standard MkDocs project consists of a configuration file and a directory containing your content:

• mkdocs.yml: The main configuration file for the project.
• docs/: The directory containing your documentation files.
  • index.md: The documentation homepage.
  • Other .md files, images, and assets reside within this folder.

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

The io.freefair.aspectj.post-compile-weaving plugin enhances existing compilation tasks (compileJava, compileGroovy, compileScala, compileKotlin) by adding an ajc action.

Workflow:

1. The source is compiled using the standard compiler (e.g., javac).
2. The resulting bytecode is passed as the -inpath argument to ajc.
3. ajc performs weaving on the bytecode.

This approach allows AspectJ to work seamlessly with annotation processors and multi-language projects.

The plugin determines the project version using a specific priority order. It stops at the first match found:

1. Explicit Version: If the project already has a version explicitly set, that version is used.
2. CI/CD Environment Variables: The plugin checks for environment variables from GitHub Actions, GitLab CI, Travis CI, CircleCI, or Jenkins.
3. Git Tags: It executes git describe --tags --exact-match to find an exact tag match.
4. Git Branch: As a final fallback, it uses git symbolic-ref --short HEAD to retrieve the current branch name.

MkDocs provides several CLI commands to manage your documentation project:

• Create a new project directory: mkdocs new [dir-name]
• Start a local development server with live-reloading: mkdocs serve
• Build the static documentation site: mkdocs build
• View available commands: mkdocs help

mkdocs new my-project
cd my-project
mkdocs serve

The io.freefair.github.package-registry-maven-publish plugin simplifies publishing to the GitHub Package Registry. It works by pre-configuring the standard Gradle [maven-publish] plugin and automatically applying the io.freefair.github.pom plugin.

Setup Requirements:

1. Credentials: You must configure a username and token in the github extension.
2. Token Scopes: The GitHub token used must have both read:packages and write:packages scopes.