scalus.compiler

Members list

Packages

Type members

Classlikes

Attributes

Supertypes: class Annotation

class Object

trait Matchable

class Any

Home of the compile / compileWithOptions macro emission — and, deliberately, the source position that every compiled program inherits at its outermost node.

Why this lives in its own file, with this name:

PlutusVx.compile(code) expands (via compileInline*) into the compileWithOptions(...) call generated below. That call is the outermost node of the whole program, so its source position becomes the program's root position. The Scala→SIR→UPLC pipeline strips source positions from most of the generated Apply/Case/Constr spine, and the post-optimization position-fill (scalus.uplc.Compiled.toUplc) back-fills those nodes from their nearest positioned ancestor — which, for framework glue with no user code inside it, is this root. So a large amount of compiler-generated glue used to be attributed to whatever line this macro happened to sit on (it was Macros.scala:589), turning that line into a fake profiling hot-spot and a call-graph hub.
Giving the macro its own file with a stable, descriptive name makes that attribution (a) self-documenting in profiles — it reads as CompiledProgramRoot:N, not a random Macros:589 — and (b) immune to line drift when unrelated macros are edited.
Tooling treats positions in this file as effectively empty (scalus.utils.ScalusSourcePos.isEffectivelyEmpty), so the position-fill and the profiler attribute generated glue to the nearest real user code instead of pooling it here. Keep this file's basename in sync with scalus.utils.ScalusSourcePos.syntheticMarkerFile.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: CompiledProgramRoot.type

Attributes

Supertypes: class Annotation

class Object

trait Matchable

class Any

Marks a trait/class as having an on-chain substitute object.

When the Scalus plugin compiles a method call on a type annotated with @OnChainSubstitute, it redirects the call to the substitute @Compile object. The substitute object must define methods matching the original trait's methods, with an additional self first parameter.

On-chain, self receives the actual qualifier value (cast via typeProxy if selfAs is specified). Off-chain, the trait works as normal OOP — the annotation is ignored.

Value parameters

selfAs

The on-chain type for self. The plugin inserts a zero-cost typeProxy cast from the trait type to selfAs. Defaults to Nothing (no cast, self keeps the original type). Example:

@OnChainSubstitute(OnChainCellOps, classOf[ScriptContext])
trait CellContext {
 def requireSignedBy(pkh: PubKeyHash): Unit
}
@Compile
object OnChainCellOps {
 def requireSignedBy(self: ScriptContext, pkh: PubKeyHash): Unit =
     require(self.txInfo.isSignedBy(pkh), "missing signature")
}

substitute

A @Compile object providing on-chain implementations for each trait method.

Attributes

Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

case class Options(targetLoweringBackend: TargetLoweringBackend = ..., targetLanguage: Language = ..., targetProtocolVersion: MajorProtocolVersion = ..., generateErrorTraces: Boolean = ..., removeTraces: Boolean = ..., optimizeUplc: Boolean = ..., uplcOptimizers: Seq[Optimizer] = ..., cseIterations: Int = ..., cceEnabled: Boolean = ..., debugLevel: Int = ..., debug: Boolean = ..., addScalusTag: Boolean = ..., warnListConversions: Boolean = ..., noWarn: Boolean = ...)

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: Options.type

Marker trait for annotations that should be propagated to SIR Module metadata.

The compiler plugin finds all annotations on @Compile objects whose class extends this trait and serializes their arguments generically into Module.anns.data. Adding a new annotation subclass requires zero plugin changes.

Keys in anns.data are "annotationClassName" for simple args or "annotationClassName:key" for Map entries.

Attributes

Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Specifies the UPLC representation for a case class, enum, or field.

When applied to a type, this annotation directs the Scalus compiler to use the specified representation instead of the default structural inference. Can also be applied to individual constructor fields for per-field representation control.

Value parameters

repr: The representation from UplcRepresentation

Attributes

Example

 @UplcRepr(UplcRepresentation.ProductCaseOneElement)
 case class PubKeyHash(hash: ByteString)
 @UplcRepr(UplcRepresentation.PackedDataMap)
 case class AssocMap[K, V](inner: List[(K, V)])
 @UplcRepr(UplcRepresentation.UplcConstr)
 case class Tile(x: BigInt, y: BigInt)
 @UplcRepr(UplcRepresentation.UplcConstr)
 case class ChessSet(
     size: BigInt,
     @UplcRepr(UplcRepresentation.SumBuiltinList(UplcRepresentation.UplcConstr))
     visited: List[Tile]
 )

Supertypes

trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Specification of UPLC type representations.

Used with the UplcRepr annotation to customize how a type or field is represented in UPLC. Also used in @Compile intrinsic code via typeProxyRepr.

This enum uses EnumCase flags so the compiler plugin recognizes its cases as constructors and produces SIR.Constr nodes. The lowering interprets these via interpretReprSIR to reconstruct the actual LoweredValueRepresentation.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: UplcRepresentation.type

Value members

Concrete methods

Compiles the given expression to a scalus.compiler.sir.SIR at compile time using the Scalus compiler plugin.

Value parameters

e: The expression to compile.

Attributes

Returns

The compiled scalus.compiler.sir.SIR.

Example

 val sir = scalus.compiler.compile(true) // Compiles the expression `true` to a SIR
 val uplc = sir.toUplc() // Converts the SIR to UPLC

Compiles the given expression to a scalus.compiler.sir.SIR at compile time using the Scalus compiler plugin, producing debug output during the compilation.

Value parameters

e: The expression to compile.

Attributes

Returns: The compiled scalus.compiler.sir.SIR.

Compiles the given expression to a scalus.compiler.sir.SIR at compile time using the Scalus compiler plugin, with explicit compiler options and debug output.

Value parameters

e: The expression to compile.
options: The compiler options to use.

Attributes

Returns: The compiled scalus.compiler.sir.SIR.

Generates a scalus.compiler.compile(code) call at compile time.

When you want to use compile in an inline method you can't do it directly, because the Scalus compiler plugin finds the call to compile and replaces it with the compiled code. Which is not what you want in this case!

For example this will not work:

 inline def myTest(inline code: Any): SIR = {
     scalus.compiler.compile(code).toUplc().evaluate
 }

Instead, you should use this method:

inline def myTest(inline code: Any): SIR = {
   scalus.compiler.compileInline(code).toUplc().evaluate
}

Attributes

Compiles the given expression to a scalus.compiler.sir.SIRType at compile time using the Scalus compiler plugin.

Type parameters

T: The type to compile.

Attributes

Returns

The compiled scalus.compiler.sir.SIRType.

Example

 // Compiles the type `BigInt` to a SIRType.Integer
 val sirType = scalus.compiler.compileType[BigInt]

Compiles the given expression to a scalus.compiler.sir.SIR at compile time using the Scalus compiler plugin, with explicit compiler options.

Value parameters

e: The expression to compile.
options: The compiler options to use.

Attributes

Returns: The compiled scalus.compiler.sir.SIR.

Collects SIR modules from the given @Compile objects at compile time.

The Scalus compiler plugin intercepts this call and replaces it with a Map[String, Module] containing the SIR modules of the referenced objects. Each argument must be a fully qualified name of a @Compile object (e.g., "scalus.compiler.intrinsics.BuiltinListOperations").

Value parameters

moduleNames: Fully qualified names of @Compile objects.

Attributes

Returns: A map from module name (with $ suffix) to scalus.compiler.sir.Module.

Returns the 0-based field index of a case-class field at compile time.

Useful in assembler mode with dropList to avoid hardcoding field offsets:

dropList(offsetOf[TxInfo](_.signatories), txInfoFields)
// expands to: dropList(BigInt(8), txInfoFields)

Type parameters

A: the case class type

Value parameters

expr: a single-level field selector, e.g. _.signatories

Attributes

Returns: the field index as BigInt

In this article

Generated with