Merge pull request #62 from Over-Run/nfd

Over-Run · Dec 7, 2024 · 2a0fd74 · 2a0fd74
2 parents 4ffcbda + a7b864e
commit 2a0fd74
Show file tree

Hide file tree

Showing 63 changed files with 4,571 additions and 1,511 deletions.
diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml
@@ -19,7 +19,7 @@ jobs:
     strategy:
       matrix:
         java: [
-          23-ea
+          23
         ]
         os: [ ubuntu-latest, windows-latest, macos-latest ]
     runs-on: ${{ matrix.os }}

diff --git a/.github/workflows/javadoc.yml b/.github/workflows/javadoc.yml
@@ -25,7 +25,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           java-version: |
-            23-ea
+            23
           distribution: 'temurin'
       - name: Grant execute permission for gradlew
         if: ${{ runner.os != 'Windows' }}

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,23 +8,26 @@ You must respect the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Issues
 
-To start with [issues](https://github.com/Over-Run/overrungl/issues), we recommend you to use the issue template.
+Issues are only for discussing bugs and proposing new features. For other discussions such as usages,
+use [discussions](https://github.com/Over-Run/overrungl/discussions).
+
+To start with [issues](https://github.com/Over-Run/overrungl/issues), you are recommended to use the issue template.
 
 ## Pull Requests
 
-We are not sure when we will review the pull request. Please note that the code must be formatted.
+The pull request will be reviewed in undetermined time, usually in active iterations which is specified in the
+[Security Policy](SECURITY.md). Please note that the code must be formatted.
 
 ### Formatted Code
 
 The formatted code:
 
-- Except auto-generated files, Java files header **MUST** contain the copy of [LICENSE](LICENSE).
-  The copy **MUST** be ended without an empty line and commented with block style, like this below:
+- The header of Java files **MUST** contain a copy of [LICENSE](LICENSE).
   ```text
   /*
    * MIT License
    *
-   * Copyright (c) 2022-2024 Overrun Organization
+   * Copyright (c) <YEAR> Overrun Organization
    *
    * Permission is hereby granted, free of charge, to any person obtaining a copy
    * of this software and associated documentation files (the "Software"), to deal
@@ -39,10 +42,10 @@ The formatted code:
   ```
   ;
 - The class names **MUST** be CamelCase;
-- The method and field names _should_ be camelCase;
-- Other rules specified by [.editorconfig](.editorconfig).
+- The method and field names _should_ be camelCase; this restriction can be widened for non-public APIs;
+- Other rules specified in [.editorconfig](.editorconfig).
 
 ## Discussions
 
-You can visit our [forum](https://github.com/Over-Run/overrungl/discussions) and create your post, share your experience
+You can visit [discussions](https://github.com/Over-Run/overrungl/discussions) and create your post, share your experience
 or just ask some questions.
diff --git a/README.md b/README.md
@@ -11,47 +11,58 @@
 ## Introduction
 
 Overrun Game Library is a high-performance library implemented with Java 23,
-which enables cross-platform access to a set of C/C++ library bindings, and provides some useful utilities.
+which enables cross-platform access to a set of C/C++ library bindings, providing various useful utilities.
 
-### OverrunGL vs. LWJGL
+### Comparing with LWJGL 3
 
-[LWJGL 3](https://github.com/LWJGL/lwjgl3) is also a Java library that enables native access.
+[LWJGL 3](https://github.com/LWJGL/lwjgl3) is also a Java library that enables cross-platform access.
 
-LWJGL 3 uses JNI to access native functions,
-but OverrunGL uses [FFM API](https://openjdk.org/jeps/454), which provides better memory management.
+LWJGL 3 uses JNI to access native functions, in OverrunGL, however,
+the [FFM API](https://openjdk.org/jeps/454) is used, which makes the linking to native functions more convenient
+as well as providing better memory management.
 
 ## Getting Started
 
 You can check our [wiki](https://github.com/Over-Run/overrungl/wiki) or
-the [samples](modules/samples/src/main/java/overrungl/demo).
+the [samples](modules/samples/src/test/java/overrungl/demo).
+
+Check [discussions](https://github.com/Over-Run/overrungl/discussions) in case you have trouble in setup works, such as environment configuring.
+
+Feel free to ask questions as long as you have searched in discussions and found no one had the same question.
 
 ## Import as a Dependency
 
 We provided a modules customizer [here](https://over-run.github.io/overrungl-gen/).
+A documentation of the customizer is [here](doc/customizer/doc_on_customizer.md).
 
-Currently, OverrunGL uses preview features, which prevent users from using newer JDKs,
-so you have to use `-SNAPSHOT` version.
+- Platform Maven coordinate: `io.github.over-run:overrungl-bom`
+- Core module Maven coordinate: `io.github.over-run:overrungl`
+- For others: `io.github.over-run:overrungl-<module-name>`
 
-You can import with `io.github.over-run:overrungl-bom:{the version}` and other submodules.
+Currently, OverrunGL uses preview features preventing users from using newer JDKs,
+so only `-SNAPSHOT` versions are provided at this time.
 
 ### Using -SNAPSHOT Versions
 
 We publish `-SNAPSHOT` versions frequently.
 
-For `-SNAPSHOT` versions, you can use
+For `-SNAPSHOT` versions, you can check
 the [list of available versions](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/over-run/overrungl/maven-metadata.xml)
 and include this maven repository:
 
-```groovy
-maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots" }
+```kotlin
+repositories {
+    maven("https://s01.oss.sonatype.org/content/repositories/snapshots")
+}
 ```
 
 ### Enable native access
 
-You must enable the access of OverrunGL by adding a VM argument or a manifest attribute.
+You must enable the access to restricted methods by adding a VM argument or a manifest attribute.
+The customizer has already included this.
 
 ```
---enable-preview-access=overrungl.core,...
+--enable-native-access=overrungl.core,...
 ```
 
 ## List of Supported Bindings
@@ -88,24 +99,20 @@ You must enable the access of OverrunGL by adding a VM argument or a manifest at
 |-----------------------------------------|-------------------------------------------------------|
 | [JOML](https://github.com/JOML-CI/JOML) | A Java math library for OpenGL rendering calculations |
 
-## Contact
-
-- [Discussions](https://github.com/Over-Run/overrungl/discussions)
-- [Discord: ![Discord](https://img.shields.io/discord/1048545705553313862)](https://discord.gg/UKRJapDKgX)
-- [QQ群](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=ahhT6p-D0HlrGat3lFDLlSB953umWh5Z&authKey=KP0UtgQg1rW8MGNV20zmxRI7OxzijOproIRsCxe8mrWD6CHBiVo0Lhr0vvrnDYAH&noverify=0&group_code=1078745269)
-
 ## Release Notes
 
 See [doc/notes](doc/notes/README.md).
 
 ## Additional
 
-Javadoc can be found [here](https://over-run.github.io/overrungl/).
+The latest Javadoc can be found [here](https://over-run.github.io/overrungl/).
 
-The documentation of OpenGL can be found from [references](https://registry.khronos.org/OpenGL-Refpages/gl4/) and [docs.gl](https://docs.gl/).
+The documentation of OpenGL can be found from [Khronos' references](https://registry.khronos.org/OpenGL-Refpages/gl4/) and [docs.gl](https://docs.gl/).
 
 OverrunGL uses [Marshal](https://github.com/Over-Run/marshal).
 
+[JavaPoet](https://github.com/palantir/javapoet) is used to generate source files.
+
 ### Credits
 
 [<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo." width="128" height="128">](https://jb.gg/OpenSourceSupport)
diff --git a/SECURITY.md b/SECURITY.md
@@ -2,19 +2,21 @@
 
 ## Supported Versions
 
-We are currently working on 0.x versions.
-
-Only the latest version will be supported.
+Only the latest version will be supported as we are currently working on 0.x versions.
 
 | Version | Supported          |
 |---------|--------------------|
 | 0.1.x   | :white_check_mark: |
 
+## Active Iterations
+
+Active iterations are some time when updates and patches are only guaranteed to be provided.
+
+From 2025 to 2027, there are two types of active iterations: the Winter Update in the early February and
+the Summer Update in July. Besides that, there is no active iteration.
+
 ## Reporting a Vulnerability
 
 You can report a vulnerability by [drafting advisory](https://github.com/Over-Run/overrungl/security/advisories/new).
 
 By reporting the vulnerability, you acknowledge that you have read and agree our [Code of Conduct](CODE_OF_CONDUCT.md).
-
-We don't accept any vulnerability in unsupported versions.
-Please keep using the latest version.
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -4,9 +4,9 @@ plugins {
     signing
 }
 
-val projGroupId: String by project
-val projVersion: String by project
-val projLicenseYear: String by project
+val projGroupId: String by rootProject
+val projVersion: String by rootProject
+val projLicenseYear: String by rootProject
 
 val jdkVersion: String by rootProject
 val jdkEnablePreview: String by rootProject
@@ -35,6 +35,11 @@ allprojects {
                         links("https://download.java.net/java/early_access/$jdkEarlyAccessDoc/docs/api/")
                     }
 
+                    links(
+                        "https://over-run.github.io/memstack/",
+                        "https://over-run.github.io/marshal/"
+                    )
+
                     tags(
                         "glfw.errors:m:Errors:",
                         "glfw.remark:m:Remarks:",

diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts
@@ -1,9 +1,23 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
 plugins { `kotlin-dsl` }
 
-dependencies {
-    implementation("org.jetbrains.kotlin.jvm:org.jetbrains.kotlin.jvm.gradle.plugin:2.0.20")
-}
+val kotlinPluginVersion: String by rootProject
+val kotlinTargetJdkVersion: String by rootProject
 
 repositories {
     mavenCentral()
 }
+
+dependencies {
+    implementation("org.jetbrains.kotlin.jvm:org.jetbrains.kotlin.jvm.gradle.plugin:$kotlinPluginVersion")
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    targetCompatibility = kotlinTargetJdkVersion
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions { jvmTarget = JvmTarget.fromTarget(kotlinTargetJdkVersion) }
+}
diff --git a/buildSrc/gradle.properties b/buildSrc/gradle.properties
@@ -0,0 +1,2 @@
+kotlinPluginVersion=2.1.0
+kotlinTargetJdkVersion=22
diff --git a/buildSrc/src/main/kotlin/GenerateTask.kt b/buildSrc/src/main/kotlin/GenerateTask.kt
@@ -1,7 +1,8 @@
-import gradle.kotlin.dsl.accessors._8758bf21ec0488ee6f70886b9f0e8378.sourceSets
 import org.gradle.api.tasks.JavaExec
+import org.gradle.api.tasks.SourceSetContainer
 import org.gradle.jvm.toolchain.JavaLanguageVersion
 import org.gradle.kotlin.dsl.get
+import org.gradle.kotlin.dsl.getByName
 import org.gradle.kotlin.dsl.provideDelegate
 
 /*
@@ -29,7 +30,7 @@ open class GenerateTask : JavaExec() {
     private val jdkEnablePreview: String by project
 
     init {
-        classpath(project.sourceSets["main"].runtimeClasspath)
+        classpath(project.extensions.getByName<SourceSetContainer>("sourceSets")["main"].runtimeClasspath)
         javaLauncher.set(javaToolchainService.launcherFor {
             languageVersion.set(JavaLanguageVersion.of(jdkVersion))
         })

diff --git a/buildSrc/src/main/kotlin/generator.conventions.gradle.kts b/buildSrc/src/main/kotlin/generator.conventions.gradle.kts
@@ -1,20 +1,12 @@
-import org.jetbrains.kotlin.gradle.dsl.JvmTarget
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
-
 plugins { kotlin("jvm") }
 
-val jdkVersion: String by rootProject
+val javaPoetVersion: String by rootProject
 val kotlinTargetJdkVersion: String by rootProject
 
-repositories { mavenCentral() }
-
-tasks.withType<KotlinCompile> {
-    compilerOptions { jvmTarget.set(JvmTarget.fromTarget(kotlinTargetJdkVersion)) }
+repositories {
+    mavenCentral()
 }
 
-tasks.withType<JavaCompile> {
-    javaCompiler.set(javaToolchains.compilerFor {
-        targetCompatibility = kotlinTargetJdkVersion
-        languageVersion.set(JavaLanguageVersion.of(jdkVersion))
-    })
+dependencies {
+    implementation("com.palantir.javapoet:javapoet:$javaPoetVersion")
 }
diff --git a/buildSrc/src/main/kotlin/module.conventions.gradle.kts b/buildSrc/src/main/kotlin/module.conventions.gradle.kts
@@ -16,6 +16,8 @@ val jdkEnablePreview: String by rootProject
 
 val targetJavaVersion = jdkVersion.toInt()
 
+val jetbrainsAnnotationsVersion: String by rootProject
+
 group = projGroupId
 version = projVersion
 
@@ -27,7 +29,7 @@ repositories {
 }
 
 dependencies {
-    compileOnly("org.jetbrains:annotations:24.1.0")
+    compileOnly("org.jetbrains:annotations:$jetbrainsAnnotationsVersion")
 }
 
 tasks.withType<JavaCompile> {

diff --git a/doc/customizer/doc_on_customizer.md b/doc/customizer/doc_on_customizer.md
@@ -0,0 +1,27 @@
+# The Modules Customizer
+
+## Introduction
+
+The modules customizer is provided in order to comfort the start of users' development.
+
+## Selecting Version
+
+Only the latest snapshot version is provided.
+
+## Selecting Modules
+
+Different _modules_ and CPU _architectures_ may be chosen.
+The customizer includes a set of _presets_, which contains various modules that are frequently used together.
+
+There is a link to a table of supported architectures.
+Note that if a module is selected with its unsupported architecture,
+the customizer will not block you from copying the code,
+but your build system will not be able to find an appropriate artifact.
+
+## Generated Code
+
+The _Gradle_ build script contains a repository for the current selected version and dependencies of selected modules.
+
+_VM Option_ contains a line of JVM argument to enable native access for selected modules.
+
+_JAR-file manifest attribute_ contains an attribute in MANIFEST.MF which just enables native access for every module. 
diff --git a/doc/legal/README.md b/doc/legal/README.md
@@ -10,4 +10,4 @@ Files:
 
 - modules/lwjgl/core/src/main/java/org/lwjgl/system/MemoryManage.java -> [modules/overrungl.core/src/main/java/overrungl/util/DebugAllocator.java](../../modules/overrungl.core/src/main/java/overrungl/util/DebugAllocator.java)
 - modules/lwjgl/core/src/main/java9/org/lwjgl/system/StackWalkUtil.java -> [modules/overrungl.core/src/main/java/overrungl/util/StackWalkUtil.java](../../modules/overrungl.core/src/main/java/overrungl/util/StackWalkUtil.java)
-- modules/samples/src/test/java/org/lwjgl/demo/util/IOUtil.java -> [modules/samples/src/main/java/overrungl/demo/util/IOUtil.java](../../modules/samples/src/main/java/overrungl/demo/util/IOUtil.java)
+- modules/samples/src/test/java/org/lwjgl/demo/util/IOUtil.java -> [modules/samples/src/test/java/overrungl/demo/util/IOUtil.java](../../modules/samples/src/test/java/overrungl/demo/util/IOUtil.java)
diff --git a/generators/nfd/build.gradle.kts b/generators/nfd/build.gradle.kts
@@ -8,5 +8,5 @@ dependencies {
 
 tasks.register<GenerateTask>("generate") {
     mainClass = "overrungl.nfd.NFDGeneratorKt"
-    workingDir = project(":nfd").projectDir.resolve("src/main/java/overrungl/nfd")
+    workingDir = project(":nfd").projectDir.resolve("src/main/java/")
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -19,7 +19,7 @@ jobs: @@
         strategy:
           matrix:
             java: [
--ea
             ]
             os: [ ubuntu-latest, windows-latest, macos-latest ]
         runs-on: ${{ matrix.os }}
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		kotlinPluginVersion=2.1.0
		kotlinTargetJdkVersion=22