A fork of ASM for the Scala compiler

This repository contains a fork of the ASM Java bytecode manipulation and analysis framework, for use by the Scala compiler.

Structure

This is a fork (a git clone) of the official ASM repository at https://gitlab.ow2.org/asm/asm.

Tags of the form ASM_X_Y* come from the upstream repo. Tags named vX.Y.Z-scala-n are created in this repo and used to release our fork under "org.scala-lang.modules" % "scala-asm".

For each ASM release there's a corresponding branch in this repo, e.g., s-9.5 for ASM 9.5. These branches start at the corresponding ASM release tag, our customizations are commits on top.

The following changes are applied:

• The package name is changed to scala.tools.asm
• Unused files are removed, including certain source files (e.g., package org.objectweb.asm.xml)
• Customizations are applied in commits marked [asm-cherry-pick]

We start a new branch for each ASM release and re-apply our changes in order to keep track what we changed. Besides, it would be non-trivial to merge in changes from upstream, as we deleted many files and moved all sources to a different directory.

Upgrading to a new version of ASM

Set up remotes

To avoid confusion, let's not call the remote origin:

• git remote rename origin upstream-github

If you haven't done so, add the upstream repository (https://gitlab.ow2.org/asm/asm) as a remote

• git remote add upstream-asm https://gitlab.ow2.org/asm/asm

Make the new version

Pull changes / tags from upstream

• git fetch upstream-asm --tags

Review the upstream changes to see if there's anything that requires attention, updates to scripts in this repo, or similar

• https://asm.ow2.io/versions.html
• git push upstream-github --tags
• https://github.com/scala/scala-asm/compare/ASM_9_4...ASM_9_5

Create a new branch s-x.y.z starting at the ASM tag for version x.y.z:

• git checkout -b s-9.5 ASM_9_5

Get the script to prepare the sources

• In the history, find the commit "Script for deleting unused files and preparing sources"
  • git log --oneline upstream-github/s-9.4 | grep 'Script for deleting'

    af285877 [asm-cherry-pick] Script for deleting unused files and preparing sources
    

• Cherry-pick
  • git cherry-pick af285877

Run the script

• ./scripts/selectAndPrepareSources

Push the branch, verify that the commits created by the script look correct

• git push --set-upstream upstream-github s-9.5

Get the build infrastructure

• In the history, find the commit "Build infrastructure" commit
  • git log --oneline upstream-github/s-9.4 | grep 'Build infra'

    06ff86de [asm-cherry-pick] Build infrastructure
    

• Cherry-pick the commit
  • git cherry-pick 06ff86de

Update the version number:

• Change the version := line in build.sbt and commit it

Check that the build works correctly

• make sure you're on JDK 8 (java -version)
• sbt clean update test publishLocal
• for f in target/*.jar; do unzip -l $f; done

Cherry-pick all commits that went on top of the previous branch

• Compare the history of the previous branch to the current branch
  • git log --oneline --graph --first-parent upstream-github/s-9.4 | grep asm-cherry-pick
  • git log --oneline --graph --first-parent @ | grep asm-cherry-pick
• Cherry-pick the commits that are not yet included
  • git cherry-pick ..., repeated for each missing SHA

Rebase and clean up

• Make sure that all commits have the [asm-cherry-pick] flag
• Clean up the history
• If there are changes to the build infrastructure, squash them into the "Build infrastructure" commit

Check that the build works correctly

• sbt clean update test publishLocal
• for f in target/*.jar; do unzip -l $f; done

Push the branch to scala/scala-asm

• git push upstream-github s-9.5
• Check the build on GitHub Actions

Create and push a tag to create a release

• git tag -s -m "scala-asm 9.5.0-scala-1" v9.5.0-scala-1 s-9.5
• git push upstream-github --tags
• Check the release build log on GitHub Actions
• Make yourself a sandwich while waiting for artifacts to appear at https://repo1.maven.org/maven2/org/scala-lang/modules/scala-asm/