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 dependencies, 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.