mirror of
https://github.com/apple/pkl.git
synced 2026-01-11 14:20:35 +01:00
116 lines
5.0 KiB
Plaintext
116 lines
5.0 KiB
Plaintext
= 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
|
|
|
|
== Setup
|
|
|
|
. (mandatory) Install {uri-jdk}[OpenJDK 17] or higher
|
|
. (recommended) Install {uri-intellij}[IntelliJ IDEA 2023.x] +
|
|
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
|
|
----
|
|
|
|
== 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 macOS executable on macOS,
|
|
# Linux and Alpine executables on Linux
|
|
# (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-amd64 # run 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/main/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]
|