buildSrc/src/main/java/cc/squirreljme/plugin/multivm/VMSpecifier.java

   1 // -*- Mode: Java; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the GNU General Public License v3+, or later.
   7 // See license.mkd for licensing and copyright information.
   8 // ---------------------------------------------------------------------------
   9
  10 package cc.squirreljme.plugin.multivm;
  11
  12 import cc.squirreljme.plugin.util.JavaExecSpecFiller;
  13 import java.io.IOException;
  14 import java.io.InputStream;
  15 import java.io.OutputStream;
  16 import java.nio.file.Path;
  17 import java.util.List;
  18 import java.util.Map;
  19 import java.util.Set;
  20 import org.gradle.api.Project;
  21 import org.gradle.api.Task;
  22 import org.gradle.api.tasks.SourceSet;
  23
  24 /**
  25  * Provider interface for the various virtual machines that are available.
  26  *
  27  * Note that source sets refer to {@link SourceSet#MAIN_SOURCE_SET_NAME}
  28  * and {@link SourceSet#TEST_SOURCE_SET_NAME}.
  29  *
  30  * @since 2020/08/06
  31  */
  32 @SuppressWarnings("InterfaceWithOnlyOneDirectInheritor")
  33 public interface VMSpecifier
  34 {
  35         /**
  36          * Returns the supported target banglets.
  37          *
  38          * @return The supported banglets for this target.
  39          * @since 2022/09/30
  40          */
  41         Set<BangletVariant> banglets();
  42
  43         /**
  44          * Dumps the library.
  45          *
  46          * @param __task The task running this, may be used to launch a VM.
  47          * @param __isTest Is this a test run?
  48          * @param __in The input data, this may be a JAR or otherwise.
  49          * @param __out The destination output file.
  50          * @throws IOException On read/write errors.
  51          * @throws NullPointerException On null arguments.
  52          * @since 2021/05/16
  53          */
  54         void dumpLibrary(VMBaseTask __task, boolean __isTest, InputStream __in,
  55                 OutputStream __out)
  56                 throws IOException, NullPointerException;
  57
  58         /**
  59          * Can this be dumped?
  60          *
  61          * @return If this can be dumped.
  62          * @since 2021/05/16
  63          */
  64         boolean hasDumping();
  65
  66         /**
  67          * Is the emulator for this JIT capable, as in there does not need to be
  68          * a library or ROM compilation before running?
  69          *
  70          * @return If this has a JIT.
  71          * @since 2022/12/23
  72          */
  73         boolean hasEmulatorJit();
  74
  75         /**
  76          * Is there a ROM task for the VM?
  77          *
  78          * @param __variant The variant used.
  79          * @return If a ROM is available.
  80          * @since 2020/08/23
  81          */
  82         boolean hasRom(BangletVariant __variant);
  83
  84         /**
  85          * Returns the name of the project that is used to run this using the
  86          * emulator.
  87          *
  88          * @param __variant The variant used.
  89          * @return The project used for running the emulator.
  90          * @since 2020/08/16
  91          */
  92         List<String> emulatorProjects(BangletVariant __variant);
  93
  94         /**
  95          * Determines the name of the library that the provider uses for what is
  96          * executed by the virtual machine and output by the virtual machine.
  97          *
  98          * @param __project The project to get from.
  99          * @param __sourceSet The source set to determine the path for.
 100          * @return The path to the source set's library.
 101          * @throws NullPointerException On null arguments.
 102          * @since 2020/08/06
 103          */
 104         String outputLibraryName(Project __project, String __sourceSet)
 105                 throws NullPointerException;
 106
 107         /**
 108          * Determines the output ROM name.
 109          *
 110          * @param __sourceSet The source set used.
 111          * @param __variant
 112          * @return The name the ROM should be.
 113          * @throws NullPointerException On null arguments.
 114          * @since 2020/11/27
 115          */
 116         String outputRomName(String __sourceSet, BangletVariant __variant)
 117                 throws NullPointerException;
 118
 119         /**
 120          * Processes the library.
 121          *
 122          * @param __task The task running this, may be used to launch a VM.
 123          * @param __isTest Is this a test run?
 124          * @param __in The input data, this may be a JAR or otherwise.
 125          * @param __out The destination output file.
 126          * @throws IOException On read/write errors.
 127          * @throws NullPointerException On null arguments.
 128          * @since 2020/08/15
 129          */
 130         void processLibrary(VMBaseTask __task, boolean __isTest, InputStream __in,
 131                 OutputStream __out)
 132                 throws IOException, NullPointerException;
 133
 134         /**
 135          * Returns the optional library dependencies needed to perform library
 136          * processing, if any.
 137          *
 138          * @param __task The owning task.
 139          * @param __variant
 140          * @return Iterable of dependent tasks.
 141          * @throws NullPointerException On null arguments.
 142          * @since 2020/11/21
 143          */
 144         Iterable<Task> processLibraryDependencies(VMBaseTask __task,
 145                 BangletVariant __variant)
 146                 throws NullPointerException;
 147
 148         /**
 149          * Processes the ROM file for linking.
 150          *
 151          * @param __task The task running under.
 152          * @param __variant The variant used.
 153          * @param __out The output of the given path.
 154          * @param __build Build parameters for the ROM.
 155          * @param __libs The libraries to link in.
 156          * @throws IOException On read/write errors.
 157          * @throws NullPointerException On null arguments.
 158          * @since 2020/11/27
 159          */
 160         void processRom(VMBaseTask __task, BangletVariant __variant,
 161                 OutputStream __out,
 162                 RomBuildParameters __build, List<Path> __libs)
 163                 throws IOException, NullPointerException;
 164
 165         /**
 166          * Fills the execution spec with the arguments used to create the
 167          * virtual machine.
 168          *
 169          * @param __task The task used as a latch to obtain the needed virtual
 170          * machine and other details.
 171          * @param __debugEligible Is this eligible for debug?
 172          * @param __execSpec The execution spec to fill.
 173          * @param __mainClass The main class to execute.
 174          * @param __commonName The common name for the program.
 175          * @param __sysProps The system properties to define.
 176          * @param __libPath The library path to use for the virtual machine.
 177          * @param __classPath The class path of the execution target.
 178          * @param __args Arguments to the started program.
 179          * @throws NullPointerException On null arguments.
 180          * @since 2020/08/15
 181          */
 182         void spawnJvmArguments(VMBaseTask __task, boolean __debugEligible,
 183                 JavaExecSpecFiller __execSpec, String __mainClass,
 184                 String __commonName, Map<String, String> __sysProps, Path[] __libPath,
 185                 Path[] __classPath, String... __args)
 186                 throws NullPointerException;
 187
 188         /**
 189          * Returns the virtual machine name using the given name format.
 190          *
 191          * @param __format The format of the name to use.
 192          * @return The formatted name.
 193          * @throws NullPointerException On null arguments.
 194          * @since 2020/08/06
 195          */
 196         String vmName(VMNameFormat __format)
 197                 throws NullPointerException;
 198
 199         /**
 200          * Is this a golden standard for testing?
 201          *
 202          * @return If this is a golden standard for testing.
 203          * @since 2022/10/01
 204          */
 205         default boolean isGoldTest()
 206         {
 207                 return false;
 208         }
 209 }