Skip to content

Latest commit

 

History

History
130 lines (107 loc) · 6.08 KB

DEVELOPMENT.adoc

File metadata and controls

130 lines (107 loc) · 6.08 KB

Development

Setup

  1. (mandatory) Install a JDK (any version between 17 - 21).

  2. (recommended) Install 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.

  3. (recommended) Install gng
    gng enables to run Gradle commands with gw (instead of ./gradlew) from any subdirectory.

  4. (recommended) Set up Git ignore-revs
    git config blame.ignoreRevsFile .git-blame-ignore-revs

  5. (recommended) Install 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:

    jenv enable-plugin gradle
jenv enable-plugin export

  6. (optional) If you’ve named the original apple/pkl git repository something other than origin, set env var PKL_ORIGINAL_REMOTE_NAME to that name in your .bashrc, .zshrc, config.fish or however you manage your local environment.

    This will allow spotless to pick the correct starting branch when formatting source code files. Otherwise, you might see that every file has its copyright year updated.

Additional Linux Setup

  1. (optional) To build the native executable (./gradlew buildNative), install Prerequisites For Native Image on Linux.

Additional Windows Setup

  1. (optional) Go to System→For developers and enable Developer Mode. Otherwise, some tests may fail due to insufficient file system privileges.

  2. (optional) To build the native executable (./gradlew buildNative), install Prerequisites For Native Image on Windows.

Common Build Commands

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

  1. Go to https://gradle.org/release-checksums/ and copy the checksum for the new Gradle version

  2. Run the following command twice (until it prints UP-TO-DATE):

    gw wrapper --gradle-version [version] --gradle-distribution-sha256-sum [sha]

  3. Commit the updated wrapper files

Update Dependencies

  1. (optional) Update gradle/libs.version.toml based on version information from https://search.maven.org, https://plugins.gradle.org, and GitHub repos

  2. Run gw updateDependencyLocks

  3. Validate changes with gw build buildNative

  4. 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