1 # OpenJDK Project Skara
  2 
  3 The goal of Project Skara is to investigate alternative SCM and code review
  4 options for the OpenJDK source code, including options based upon Git rather than
  5 Mercurial, and including options hosted by third parties.
  6 
  7 This repository contains tooling for working with OpenJDK projects and
  8 their repositories. The following CLI tools are available as part of this
  9 repository:
 10 
 11 - git-jcheck - a backwards compatible Git port of [jcheck](https://openjdk.java.net/projects/code-tools/jcheck/)
 12 - git-webrev - a backwards compatible Git port of [webrev](https://openjdk.java.net/projects/code-tools/webrev/)
 13 - git-defpath - a backwards compatible Git port of [defpath](https://openjdk.java.net/projects/code-tools/defpath/)
 14 - git-fork - fork a project on an external Git source code hosting provider to your personal space and optionally clone it
 15 - git-pr - interact with pull requests for a project on an external Git source code hosting provider
 16 - git-info - show OpenJDK information about commits, e.g. issue links, authors, contributors, etc.
 17 - git-token - interact with a Git credential manager for handling personal access tokens
 18 - git-translate - translate between [Mercurial](https://mercurial-scm.org/)
 19 and [Git](https://git-scm.com/) hashes
 20 - git-skara - learn about and update the Skara CLI tools
 21 
 22 There are also CLI tools available for importing OpenJDK
 23 [Mercurial](https://mercurial-scm.org/) repositories into
 24 [Git](https://git-scm.com/) repositories and vice versa:
 25 
 26 - git-openjdk-import
 27 - git-verify-import
 28 - hg-openjdk-import
 29 
 30 The following server-side tools (so called "bots") for interacting with
 31 external Git source code hosting providers are available:
 32 
 33 - hgbridge - continuously convert Mercurial repositories to git
 34 - mlbridge - bridge messages between mailing lists and pull requests
 35 - notify - send email notifications when repositories are updated
 36 - pr - add OpenJDK workflow support for pull requests
 37 - submit - example pull request test runner
 38 
 39 ## Building
 40 
 41 [JDK 12](http://jdk.java.net/12/) or later and [Gradle](https://gradle.org/)
 42 5.6.2 or later is required for building. To build the project on macOS or
 43 GNU/Linux x64, just run the following command from the source tree root:
 44 
 45 ```bash
 46 $ sh gradlew
 47 ```
 48 
 49 To build the project on Windows x64, run the following command from the source tree root:
 50 
 51 ```bat
 52 > gradlew
 53 ```
 54 
 55 The extracted jlinked image will end up in the `build` directory in the source
 56 tree root.
 57 
 58 ### Other operating systems and CPU architectures
 59 
 60 If you want to build on an operating system other than GNU/Linux, macOS or
 61 Windows _or_ if you want to build on a CPU architecture other than x64, then
 62 ensure that you have JDK 12 or later installed locally. You can then run the
 63 following command from the source tree root:
 64 
 65 ```bash
 66 $ sh gradlew
 67 ```
 68 
 69 The extracted jlinked image will end up in the `build` directory in the source
 70 tree root.
 71 
 72 ### Offline builds
 73 
 74 If you don't want the build to automatically download any depenendcies, then
 75 you must ensure that you have installed the following software locally:
 76 
 77 - JDK 12 or later
 78 - Gradle 5.6.2 or later
 79 
 80 To create a build then run the command
 81 
 82 ```bash
 83 $ gradle offline
 84 ```
 85 
 86 _Please note_ that the above command does _not_ make use of `gradlew` to avoid
 87 downloading Gradle.
 88 
 89 The extracted jlinked image will end up in the `build` directory in the source
 90 tree root.
 91 
 92 ### Cross-linking
 93 
 94 It is also supported to cross-jlink jimages to GNU/Linux, macOS and/or Windows from
 95 any of the aforementioned operating systems. To build all applicable jimages
 96 (including the server-side tooling), run the following command from the
 97 source tree root:
 98 
 99 ```bash
100 sh gradlew images
101 ```
102 
103 ## Installing
104 
105 To install the Skara tools, include the `skara.gitconfig` Git configuration
106 file in your user-level Git configuration file. On macOS or
107 GNU/Linux:
108 
109 ```bash
110 $ git config --global include.path "$PWD/skara.gitconfig"
111 ```
112 
113 On Windows:
114 
115 ```bat
116 > git config --global include.path "%CD%/skara.gitconfig"
117 ```
118 
119 To check that everything works as expected, run the command `git skara help`.
120 
121 ## Testing
122 
123 [JUnit](https://junit.org/junit5/) 5.5.1 or later is required to run the unit
124 tests. To run the tests, execute following command from the source tree root:
125 
126 ```bash
127 $ sh gradlew test
128 ```
129 
130 The tests expect [Git](https://git-scm.com/) version 2.19.1 or later and
131 [Mercurial](https://mercurial-scm.org/) 4.7.1 or later to be installed on
132 your system.
133 
134 This repository also contains a Dockerfile, `test.dockerfile`, that allows
135 for running the tests in a reproducible way with the proper dependencies
136 configured. To run the tests in this way, run the following command from the
137 source tree root:
138 
139 ```bash
140 $ sh gradlew reproduce
141 ```
142 
143 ## Wiki
144 
145 Project Skara's wiki is available at <https://wiki.openjdk.java.net/display/skara>.
146 
147 ## Issues
148 
149 Issues are tracked in the [JDK Bug System](https://bugs.openjdk.java.net/)
150 under project Skara at <https://bugs.openjdk.java.net/projects/SKARA/>.
151 
152 ## Contributing
153 
154 We are more than happy to accept contributions to the Skara tooling, both via
155 patches sent to the Skara
156 [mailing list](https://mail.openjdk.java.net/mailman/listinfo/skara-dev) and in the
157 form of pull requests on [GitHub](https://github.com/openjdk/skara/pulls/).
158 
159 ## Members
160 
161 See <http://openjdk.java.net/census#skara> for the current Skara
162 [Reviewers](https://openjdk.java.net/bylaws#reviewer),
163 [Committers](https://openjdk.java.net/bylaws#committer) and
164 [Authors](https://openjdk.java.net/bylaws#author). See
165 <https://openjdk.java.net/projects/> for how to become an author, committer
166 or reviewer in an OpenJDK project.
167 
168 ## Discuss
169 
170 Development discussions take place on the project Skara mailing list
171 `skara-dev@openjdk.java.net`, see
172 <https://mail.openjdk.java.net/mailman/listinfo/skara-dev> for instructions
173 on how to subscribe of if you want to read the archives. You can also reach
174 many project Skara developers in the `#openjdk` IRC channel on
175 [OFTC](https://www.oftc.net/), see <https://openjdk.java.net/irc/> for details.
176 
177 ## License
178 
179 See the file `LICENSE` for details.