-
Notifications
You must be signed in to change notification settings - Fork 288
/
Copy pathDEVELOPMENT.adoc
122 lines (100 loc) · 5.42 KB
/
DEVELOPMENT.adoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
= Development
:uri-gng: https://gng.dsun.org
:uri-jenv: https://www.jenv.be
:uri-intellij: https://www.jetbrains.com/idea/download/
:uri-jdk: https://adoptopenjdk.net/releases.html?variant=openjdk17
:uri-native-prerequisites: https://www.graalvm.org/latest/getting-started/windows/#prerequisites-for-native-image-on-windows
== Setup
. (mandatory) Install {uri-jdk}[OpenJDK 17] or higher
. (recommended) Install {uri-intellij}[IntelliJ IDEA] +
To import the project into IntelliJ, go to File->Open and select the project's root directory.
If the project is opened but not imported, look for a popup in the lower right corner
and click its "Import Gradle Project" link.
. (recommended) Install {uri-gng}[gng] +
_gng_ enables to run Gradle commands with `gw` (instead of `./gradlew`) from any subdirectory.
. (recommended) Set up Git ignore-revs +
`git config blame.ignoreRevsFile .git-blame-ignore-revs`
. (recommended) Install {uri-jenv}[jenv] and plugins +
_jenv_ use specific JDK versions in certain subdirectories. _Pkl_ comes with a `.java-version` file specifying JDK 17. +
Enable _jenv_ plugins for better handling by `gradle`:
+
[source,shell]
----
jenv enable-plugin gradle
jenv enable-plugin export
----
=== Additional Windows Setup
. (optional) Go to `System->For developers` and enable `Developer Mode`.
Otherwise, some tests may fail due to insufficient file system privileges.
. (optional) To build the native executable (`./gradlew buildNative`),
install {uri-native-prerequisites}[Prerequisites For Native Image on Windows].
== Common Build Commands
[source,shell]
----
gw clean
gw test # run all tests except native executable tests
gw testNative # run native executable tests
gw spotlessApply # fix code formatting
gw build # build everything except native executables
gw buildNative # build native executable(s) for current platform
# (Alpine executable is only built if ~/staticdeps/bin/musl-gcc exists)
pkl-cli/build/executable/jpkl # run Java executable
pkl-cli/build/executable/pkl-macos-aarch64 # run Mac executable
pkl-cli/build/executable/pkl-macos-amd64 # run Intel Mac executable
pkl-cli/build/executable/pkl-linux-amd64 # run Linux executable
pkl-cli/build/executable/pkl-alpine-linux-amd64 # run Alpine Linux executable
pkl-cli/build/executable/pkl-windows-amd64.exe # run Windows executable
----
== Update Gradle
. Go to https://gradle.org/release-checksums/ and copy the checksum for the new Gradle version
. Run the following command *twice* (until it prints UP-TO-DATE):
+
[source,shell]
----
gw wrapper --gradle-version [version] --gradle-distribution-sha256-sum [sha]
----
. Commit the updated wrapper files
== Update Dependencies
. (optional) Update _gradle/libs.version.toml_
based on version information from https://search.maven.org, https://plugins.gradle.org, and GitHub repos
. Run `gw updateDependencyLocks`
. Validate changes with `gw build buildNative`
. Review and commit the updated dependency lock files
== Code Generation
* Truffle code generation is performed by Truffle's annotation processor, which runs as part of task `:pkl-core:compileJava`
** Output dir is `generated/truffle/`
* ANTLR code generation is performed by task `:pkl-core:generateGrammarSource`
** Output dir is `generated/antlr/`
== Remote JVM Debugging
To enable remote JVM debugging when running Gradle tasks (e.g. test), add the flag `-Djvmdebug=true`.
This will listen on port 5005.
Example: `./gradlew test -Djvmdebug=true`
== Resources
For automated build setup examples see our https://github.com/apple/pkl/blob/main/.circleci/[CircleCI] jobs like our https://github.com/apple/pkl/blob/main/.circleci/jobs/BuildNativeJob.pkl[BuildNativeJob.pkl], where we build Pkl automatically.
=== ANTLR
* https://github.com/antlr/antlr4/blob/master/doc/index.md[Documentation]
* https://groups.google.com/forum/#!forum/antlr-discussion[Forums]
* https://github.com/mobileink/lab.clj.antlr/tree/main/doc[Some third-party docs]
=== Truffle
* http://ssw.jku.at/Research/Projects/JVM/Truffle.html[Homepage]
* https://github.com/graalvm/truffle[GitHub]
* http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/[Javadoc]
* http://mail.openjdk.java.net/pipermail/graal-dev/[Mailing List]
* https://medium.com/@octskyward/graal-truffle-134d8f28fb69#.2db370y2g[Graal & Truffle (Article)]
* https://comserv.cs.ut.ee/home/files/Pool_ComputerScience_2016.pdf?study=ATILoputoo&reference=6319668E7151D556131810BC3F4A627D7FEF5F3B[Truffle Overview (see chapter 1)]
* https://gist.github.com/smarr/d1f8f2101b5cc8e14e12[Truffle: Languages and Material]
* https://github.com/smarr/truffle-notes[Truffle Notes]
* https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines[Truffle FAQ]
=== Other Config Languages
* https://github.com/google/jsonnet[Jsonnet]
* https://github.com/dhall-lang/dhall-lang[Dhall]
* https://cuelang.org[CUE]
* https://nickel-lang.org[Nickel]
* https://kcl-lang.io[KCL]
* https://github.com/google/skylark[Skylark]
* https://github.com/typesafehub/config[Typesafe Config]
* https://www.flabbergast.org[Flabbergast]
(defunct, http://artefacts.masella.name/2015-srecon-andre_masella.pdf[paper])
* https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55[Nix by example: The Nix expression language]
* http://lethalman.blogspot.co.at/2014/07/nix-pill-4-basics-of-language.html[Nix pill 4: the basics of the language]
* https://docs.puppetlabs.com/puppet/latest/reference/lang_summary.html[Puppet Configuration Language]