create_fork.sh: Script to Create a New Fork (#296)

* Script to Create a New Fork

* validate fork name

* use interactive prompt to prevent accidentally overwriting existing fork

* recommend create_fork.sh in the README

* remove mention of additional_builds_steps (obsolete)

---------

Co-authored-by: Jason Nochlin <hundredwatt@users.noreply.github.com>

README.md

@@ -272,13 +272,14 @@ If you want to use a build not available via these channels, reach out to discus
 To submit your own implementation to 1BRC, follow these steps:
 
 * Create a fork of the [onebrc](https://github.com/gunnarmorling/onebrc/) GitHub repository.
-* Create a copy of _CalculateAverage.java_, named _CalculateAverage\_<your_GH_user>.java_, e.g. _CalculateAverage\_doloreswilson.java_.
+* Run `./create_fork.sh <your_GH_user>` to copy the baseline implementation to your personal files, or do this manually:
-* Make that implementation fast. Really fast.
+  * Create a copy of _CalculateAverage.java_, named _CalculateAverage\_<your_GH_user>.java_, e.g. _CalculateAverage\_doloreswilson.java_.
-* Create a copy of _calculate\_average\_baseline.sh_, named _calculate\_average\_<your_GH_user>.sh_, e.g. _calculate\_average\_doloreswilson.sh_.
+  * Create a copy of _calculate\_average\_baseline.sh_, named _calculate\_average\_<your_GH_user>.sh_, e.g. _calculate\_average\_doloreswilson.sh_.
-* Adjust that script so that it references your implementation class name. If needed, provide any JVM arguments via the `JAVA_OPTS` variable in that script.
+  * Adjust that script so that it references your implementation class name. If needed, provide any JVM arguments via the `JAVA_OPTS` variable in that script.
     Make sure that script does not write anything to standard output other than calculation results.
-* (Optional) OpenJDK 21 is used by default. If a custom JDK build is required, create a copy of _prepare\_baseline.sh_, named _prepare\_<your_GH_user>.sh_, e.g. _prepare\_doloreswilson.sh_. Include the SDKMAN command `sdk use java [version]` in the your prepare script.
+  * (Optional) OpenJDK 21 is used by default. If a custom JDK build is required, create a copy of _prepare\_baseline.sh_, named _prepare\_<your_GH_user>.sh_, e.g. _prepare\_doloreswilson.sh_. Include the SDKMAN command `sdk use java [version]` in the your prepare script.
-* (Optional) If you'd like to use native binaries (GraalVM), create a script named _additional\_build\_step\_<your_GH_user>.sh_, e.g. _additional\_build\_step\_doloreswilson.sh_ and add all the required build logic there
+  * (Optional) If you'd like to use native binaries (GraalVM), add all the required build logic to your _prepare\_<your_GH_user>.sh_ script.
+* Make that implementation fast. Really fast.
 * Run the test suite by executing _/test.sh <your_GH_user>_; if any differences are reported, fix them before submitting your implementation.
 * Create a pull request against the upstream repository, clearly stating
   * The name of your implementation class.

create_fork.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+#
+#  Copyright 2023 The original authors
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+
+set -eo pipefail
+
+SOURCE_FORK="baseline"
+
+usage() {
+  echo "Usage: create_fork.sh [-s <source fork>] <fork name>"
+  echo "  -s <source fork>  The name of the fork to copy from (default: baseline)"
+  echo "  <fork name>       The name of the fork to create"
+  exit 1
+}
+
+# Parse
+while getopts ":s:" opt; do
+  case ${opt} in
+    s )
+      SOURCE_FORK=$OPTARG
+      ;;
+    \? )
+      usage
+      exit 1
+      ;;
+    : )
+      echo "Invalid option: $OPTARG requires an argument" 1>&2
+      exit 1
+      ;;
+  esac
+done
+
+FORK=${@:$OPTIND:1}
+if [ -z "$FORK" ]
+  then
+    usage
+    exit 1
+fi
+
+# validate the fork name has only [a-zA-Z0-9_] and then error otherwise to let the user fix
+if [[ ! "$FORK" =~ ^[a-zA-Z0-9_]+$ ]]; then
+  echo "Fork name must only contain characters result in a valid Java class name  [a-zA-Z0-9_]"
+  exit 1
+fi
+
+
+# helper function
+function substitute_in_file {
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    sed -i '' "s/$1/$2/g" $3
+  else
+    sed -i "s/$1/$2/g" $3
+  fi
+}
+
+set -x
+
+# create new fork
+
+cp -i prepare_$SOURCE_FORK.sh prepare_$FORK.sh
+
+cp -i calculate_average_$SOURCE_FORK.sh calculate_average_$FORK.sh
+substitute_in_file $SOURCE_FORK $FORK calculate_average_$FORK.sh
+
+if [ $SOURCE_FORK == "baseline" ]; then
+  cp -i src/main/java/dev/morling/onebrc/CalculateAverage.java src/main/java/dev/morling/onebrc/CalculateAverage_$FORK.java
+  substitute_in_file CalculateAverage CalculateAverage_$FORK src/main/java/dev/morling/onebrc/CalculateAverage_$FORK.java
+else
+  cp -i src/main/java/dev/morling/onebrc/CalculateAverage_$SOURCE_FORK.java src/main/java/dev/morling/onebrc/CalculateAverage_$FORK.java
+  substitute_in_file $SOURCE_FORK $FORK src/main/java/dev/morling/onebrc/CalculateAverage_$FORK.java
+fi
+