Repository files navigation

The goal of Project Skara is to investigate alternative SCM and code reviewoptions for the OpenJDK source code, including options based upon Git rather thanMercurial, and including options hosted by third parties.

This repository contains tooling for working with OpenJDK projects andtheir repositories. The following CLI tools are available as part of thisrepository:

• git-jcheck - a backwards compatible Git port ofjcheck
• git-webrev - a backwards compatible Git port ofwebrev
• git-defpath - a backwards compatible Git port ofdefpath
• git-fork - fork a project on an external Git source code hosting provider to your personal space and optionally clone it
• git-sync - sync the personal fork of the project with the current state of the upstream repository
• git-pr - interact with pull requests for a project on an external Git source code hosting provider
• git-info - show OpenJDK information about commits, e.g. issue links, authors, contributors, etc.
• git-token - interact with a Git credential manager for handling personal access tokens
• git-translate - translate betweenMercurialandGit hashes
• git-skara - learn about and update the Skara CLI tools
• git-trees - run a git command in a tree of repositories
• git-publish - publishes a local branch to a remote repository
• git-backport - backports a commit from another repository onto the current branch

There are also CLI tools available for importing OpenJDKMercurial repositories intoGit repositories and vice versa:

• git-openjdk-import
• git-verify-import
• hg-openjdk-import

The following server-side tools (so called "bots") for interacting withexternal Git source code hosting providers are available:

• hgbridge - continuously convert Mercurial repositories to git
• mlbridge - bridge messages between mailing lists and pull requests
• notify - send email notifications when repositories are updated
• pr - add OpenJDK workflow support for pull requests
• submit - example pull request test runner
• forward - forward commits to various repositories
• mirror - mirror repositories
• merge - merge commits between different repositories and/or branches
• test - test runner

JDK 21 or later andGradle8.5 or later are required for building and will be automatically downloadedand installed by the custom gradlew script. To build the project on macOS orGNU/Linux x64, just run the following command from the source tree root:

$ sh gradlew

To build the project on Windows x64, run the following command from the sourcetree root:

> gradlew

The extracted jlinked image will end up in thebuild directory in the sourcetree root.Note that the above commands will build the CLI tools, if youalso want to build the bot images runsh gradlew images on GNU/Linux orgradlew images on Windows.

If you want to build on an operating system other than GNU/Linux, macOS orWindowsor if you want to build on a CPU architecture other than x64, thenensure that you have a JDK of suitable version or later installed locally andJAVA_HOME set to point to it. You can then run the following command from thesource tree root:

$ sh gradlew

The extracted jlinked image will end up in thebuild directory in the sourcetree root.

If you don't want the build to automatically download any dependencies, thenyou must ensure that you have installed the following software locally (seeversion requirements above):

• JDK
• Gradle

To create a build then run the command:

$ gradle offline

Please note that the above command doesnot make use ofgradlew to avoiddownloading Gradle.

The extracted jlinked image will end up in thebuild directory in the sourcetree root.

It is also supported to cross-jlink jimages to GNU/Linux, macOS and/or Windows fromany of the aforementioned operating systems. To build all applicable jimages(including the server-side tooling), run the following command from thesource tree root:

sh gradlew images

Skara also has a very thin Makefile wrapper for contributors who prefer to buildusingmake. To build the jlinked image for the CLI tools usingmake, run:

make

There are multiple ways to install the Skara CLI tools. The easiest way is tojust includeskara.gitconfig in your global Git configuration file. You can alsoinstall the Skara tools on your$PATH.

To install the Skara tools, include theskara.gitconfig Git configurationfile in your user-level Git configuration file. On macOS orGNU/Linux:

$ git config --global include.path"$PWD/skara.gitconfig"

On Windows:

> git config --global include.path"%CD%/skara.gitconfig"

To check that everything works as expected, run the commandgit skara help.

The Skara tools can also be added to$PATH on GNU/Linux and macOS and Gitwill pick them up. You can either just extend$PATH with thebuild/bindirectory or you can copy the tools to a location already on$PATH. To extend$PATH with thebuild/bin directory, run:

$ sh gradlew$export PATH="$PWD/build/bin:$PATH"

To copy the tools to a location already on$PATH, run:

$ make$ make install prefix=/path/to/install/location

When runningmake install the default value ofprefix is$HOME/.local.

If you wantgit help <skara tool> (or the equivalentman git-<skara tool>to work, you must also add thebuild/bin/man directory to$MANPATH.For instance, run this from the Skara top directory to add this to your.bashrc file:

echo"export MANPATH=\$MANPATH":$PWD/build/bin/man>>~/.bashrc

JUnit 5.8.2 or later is required to run the unittests. To run the tests, execute following command from the source tree root:

$ sh gradlewtest

If you prefer to use the Makefile wrapper you can also run:

$ maketest

The tests expectGit version 2.19.3 or later andMercurial 4.7.2 or later to be installed onyour system.

This repository also contains a Dockerfile,test.dockerfile, that allowsfor running the tests in a reproducible way with the proper dependenciesconfigured. To run the tests in this way, run the following command from thesource tree root:

$ sh gradlew reproduce

If you prefer to use the Makefile wrapper you can also run:

$ make reproduce

There are no additional dependencies required for developing Skara if you canalready build and test it (see above for instructions). The command-line toolsand libraries supports all of GNU/Linux, macOS and Windows and can therefore bedeveloped on any of those operating systems. The bots primarily support macOSand GNU/Linux and may requireWindows Subsystem forLinux on Windows.

Please see the sections below for instructions on setting up a particular editoror IDE.

If you choose to useIntelliJ IDEA as yourIDE when working on Skara you can simply open the root folder and the projectshould be automatically imported. You will need to configure a Platform SDK thatis of the appropriate version (see above). Either set this up manually, orbuild once from the terminal, which will download a suitable JDK.Configure IntelliJ to use it atFile → Project Structure → Platform Settings → SDKs → + → Add JDK... and browse to the downloaded JDK foundin<skara-folder>/.jdk/. For example, on macOS, select the<skara-folder>/.jdk/openjdk-21_osx-x64_bin/jdk-21.jdk/Contents/Home folder.

If you choose to useVim as your editor when working on Skara then youprobably also want to utilize the Makefile wrapper. The Makefile wrapper enablesto you to run:make and:make tests in Vim.

Project Skara's wiki is available athttps://wiki.openjdk.org/display/skara.

Issues are tracked in theJDK Bug Systemunder project Skara athttps://bugs.openjdk.org/projects/SKARA/.

We are more than happy to accept contributions to the Skara tooling, both viapatches sent to the Skaramailing list and in theform of pull requests onGitHub.

Seehttp://openjdk.org/census#skara for the current SkaraReviewers,Committers andAuthors. Seehttps://openjdk.org/projects/ for how to become an author, committeror reviewer in an OpenJDK project.

Development discussions take place on the project Skara mailing listskara-dev@openjdk.org, seehttps://mail.openjdk.org/mailman/listinfo/skara-dev for instructionson how to subscribe of if you want to read the archives. You can also reachmany project Skara developers in the#openjdk IRC channel onOFTC, seehttps://openjdk.org/irc/ for details.

See the fileLICENSE for details.