Skip to content

Commit

Permalink
Updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lagergren
lagergren committed Feb 12, 2024
1 parent 8409bb7 commit 5a8ff3c
Showing 1 changed file with 71 additions and 18 deletions.
89 changes: 71 additions & 18 deletions manualTests/build.gradle.kts
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,38 @@
import org.xtclang.plugin.tasks.XtcCompileTask
import org.xtclang.plugin.tasks.XtcRunTask

/**
* This is the manualTests project.
*
* Test utilities. This is a standalone XTC project, which should only depend on the XDK.
* This is a standalone XTC project, which should only depend on the XDK.
* If we want to use it to debug the XDK, that is also fine, as it will do dependency
* substitution on the XDK and XTC Plugin (and Javatools and other dependencies) correctly,
* through included builds, anyway.
*
* This is compiled as part of the XDK build, in order to ensure that the build DSL work as
* expected, and that we can resolve modules only with external dependencies to repository
* artifacts for the XTC Gradle plugin and the XDK.
* Depending on the "manualTests" propertie set in ../gradle.propeties, this project
* will either be an includedBuild in the XDK build, but will only configure, not resolve or
* compile anything. The overhead using the Gradle cache should be minimal. If you set the
* manualTests flag to false, you can still run and test this project from the command line
* by specifying its path from the prompt, just like any external gradle project.
*
* Either way, you can always run these tasks from the CLI (or if you have the build included
* from inside IntelliJ, and actually debug and test these tasks and the XDK implementation code
* in the IDE).
*
* Commands to test (where <SourceSet> is empty for 'main', and 'test' for test (not used yet)):
*
* Some ways to test (where <SourceSet> is empty for 'main', and 'test' for test (not used yet)):
* ./gradlew :manualTests:run<SourceSet>Xtc (will execute the modules along with arguments etc, from the xtcRun extension config)
* ./gradlew :manualTests:run<SourceSet>Xtc -PmoduleName=TestArray (will override the xtcRun configuration and run the source set output module named TestArray)
* ./gradlew :manualTests:run<SourceSet>AllXtc (will execute every module created in the source set output)
* ./gradlew :manualTests:compile<SourceSet>Xtc (will compile the source set)
*
* (or their corresponding IntelliJ actions, i.e. right click in the Gradle hierarchy, and set up the
* appropriate run and debug configuration for Gradle jobs).
*/

/**
* Plugins required. This is done through the Gradle version catalog mechanism. A version catalog
* PLUGIN SECTION.
*
* These are resolved through the Gradle version catalog mechanism. A version catalog
* is a single source of truth for dependent artifacts for a Gradle oroject. For the XVM repo,
* there is a "global" version catalog under $compositeBuildRootDirectory/gradle/libs/libs.versions.html.
* This makes it possible to alias artifacts to type safe (compile time knowable) hierarchical names.
Expand All @@ -34,8 +45,7 @@ import org.xtclang.plugin.tasks.XtcRunTask
* }
*
* in your project settings, or defined in the build file (if you can, it is recommended to keep it in
* settings (for a best-practise example, please see the XTC Platform project and its XTC Plugin branch,
* which is either up for review as a pull request or already merged to master)), the build will look
* settings (for a best-practise example, please see the xtc-template-app project), the build will look
* for the artifact in any local caches, and if not found, then ask the mavenCentral artifact repo
* to if it knows about it and downloads/caches it. Basically, for any artifact on which you depend,
* you need to know group, id and version, to fully resolve it. Sometimes you are only interested in
Expand All @@ -59,9 +69,11 @@ plugins {
}

/**
* Dependencies required. The xdk cam be retrieved with the "xdk" consumer configuration, which
* will look for a file/dir hierarchy that contains the modules from the javatools and lib directories
* of an XTC installation. We currently publish XDK releases as zipped artifacts in our GitHub Maven
* DEPENDENCIES SECTION
*
* The xdk cam be retrieved with the "xdk" consumer configuration, which will look for a file/dir
* hierarchy that contains the modules from the javatools and lib directories of an XTC installation.
* We currently publish XDK releases as zipped artifacts in our GitHub Maven
* repositoru (and soon also on mavenCentral after the next official release). If you want to use
* a zipped XDK artifact, use the "xdkDistribution" depeendency instead. Again, we recommend you
* look at the XTC platform repository, or the XTC template app, that is a simple Hello World, to
Expand All @@ -72,7 +84,13 @@ dependencies {
}

/**
* This configured a source set, which makes the compiler build all of the included modules.
* SOURCE SETS SECTION
*
* This configures source sets, which makes the compiler build all of the included modules.
* in that source set, in tasks containing that source set name (except for Main which is
* a blank string in its tasks), e.g. compileXtc compiles the main source set, compileTestXtc
* compiles the test source set and so on.
* <p>
* There are several negative "should fail" source files in this subproject as well. but
* these are filtered out through the standard Gradle source set mechanism. This repo
* is not really meant to be used as a unit test. It merely sits on top of everything to
Expand Down Expand Up @@ -109,7 +127,7 @@ sourceSets {
"**/misc.x",
"**/queues.x",
"**/services.x",
//"**/TestSimple.x",
"**/TestSimple.x",
"**/reflect.x",
"**/regex.x",
"**/tuple.x"
Expand Down Expand Up @@ -137,7 +155,7 @@ sourceSets {
* we have a default source set for xtc code called "main" and one called "test" (currently not
* used for much). The name of a compile task is derived from the name of the source set it will
* compile, and upon detecting changes, recompile. Hence, if you have a "test" source set, you
* will be given a "compileTextXtc" task, just as it would work with Java, Scala, Clojure etc.
* will be given a "compileTestXtc" task, just as it would work with Java, Scala, Clojure etc.
* For the default source set (by convention always renamed "main"), the task will just be called
* "compileXtc", just like the default Java plugin compile task for the main source set is called
* "compileJava". Since the plugin currently creates XTC main and test source sets by default, you
Expand Down Expand Up @@ -171,6 +189,7 @@ sourceSets {
* To see more information on why a task is re-run, skipped or retrieved from the build cache,
* you can run Gradle with the --info flag.
*
* To configure compilation for other source sets, use their xtc<SourceSet>Compile DSLs instead.
*/
xtcCompile {
/*
Expand Down Expand Up @@ -218,6 +237,9 @@ xtcCompile {
// stdin = System.`in`
}

/**
* To configure compilation for other source sets, use their xtc<SourceSet>Compile DSLs instead.
*/
xtcRun {
/*
* Equivalent to the "--version" flag for the launcher (default: false).
Expand Down Expand Up @@ -259,7 +281,7 @@ xtcRun {
* -PmoduleName=<name>, -PmoduleMethod=<method name, default "run"> and -PmoduleArgs=<default none>
* on the command line will override the xtcRun module configuration for a project. This is
* a way that can be used to run and debug single tests in this project. Note that any existing
* run module configuraiton gets thrown away and gets replaced by the command line definition if
* run module configuration gets thrown away and gets replaced by the command line definition if
* you do this. Also note that the command line definition is treated like any module definition, and
* will be a registered input for xtcRunTasks for any source set.
*/
Expand All @@ -273,9 +295,40 @@ xtcRun {
}
}

// First make sure we support an alternative runner
// This shows how to add a custom run task that overrides the global xtcRun config
// or xtc<SourceSet>Run configs.
val runXtcWithTaskLevelConfiguration by tasks.registering(XtcRunTask::class) {
moduleName("TestSimple")
}

val runParallel by tasks.registering(XtcRunTask::class) {
moduleName("Runner")
module {
moduleName("Runner")
}
/* modulesArgs(
"TestAnnotations",
"TestArray",
"TestCollections",
"TestDefAsn",
"TestTry",
"TestGenerics",
"TestInnerOuter",
"TestFiles",
"TestIO",
"TestLambda",
"TestLiterals",
"TestLoops",
"TestNesting",
"TestNumbers",
"TestProps",
"TestMaps",
"TestMisc",
"TestQueues",
"TestServices",
"TestReflection",
"TestRegularExpressions",
"TestTuples"
)*
}
/*
Expand Down

0 comments on commit 5a8ff3c

Please sign in to comment.