Merlin Builder
Overview[edit]
Merlin Builder is a tool available to Merlin Mavens™ that provides the required functionality to build a challenge for use by Merlin Mission Manager . Any supported language may be used for the challenge (though the generator and verifier must be written in Swift).
The Merlin Mission Manager verifies challenges through a multi-step process. The following steps occur each and every time that a student executes merlin test:
- A generator generates a problem set. The problem set serves as input to the student's program by providing:
- Standard input (e.g. simulates a user's keyboard input)
- Command line arguments
- Text replacement within zero or more of the student's program files. This is referred to as excision because a portion of the student's program file is removed during this process.
- Expected standard output
- After the problem set is generated, the student's program is built using make.sh. The program will include any text replaced during the excision process.
- The student's (potentially modified) program is executed using run.sh and both standard output and standard input are spooled to a file
- A verifier compares the actual standard output with the expected standard output and determines whether or not the execution was successful
Usage[edit]
There are only five builder subcommands as the majority of the process involves coding of the generator.
merlin builder init
: Initializes the directory structure and must be the first command executed in an empty directorymerlin builder prepare
: Similar to the parallelmerlin prepare
, copies the source files to serve as a starting point for the studentmerlin builder test
: Similar to the parallelmerlin test
, executes the generator and verifiermerlin builder reference
: Copies a reference solution from the reference subdirectory, required for all challengesmerlin builder package
: Packages the entire challenge into a single file, suitable for exchange
Getting Started[edit]
For this example, navigate to your Experiences directory and create an empty directory named CtoF
Run merlin builder init inside your newly-created directory. This creates the required Merlin Builder directory structure
john-williams@codermerlin:~/Experiences/CtoF merlin builder init
Navigate to the sources directory, and open instructions.txt in emacs. These are the instructions that the student will see when they prepare the mission
john-williams@codermerlin:~/Experiences/CtoF/sources emacs instructions.txt
Since this mission will require the user to convert a given temperature from Celsius to Farenheight, change the instructions to tell the user to convert from C to F given constant c. Save and exit emacs
Next, open main.swift in emacs
john-williams@codermerlin:~/Experiences/CtoF/sources emacs main.swift
Remove the constant definition and create a constant c equal to 21.2 Append let degreesF = 0 above the print statement Change the print statement to print degreesF Save and exit emacs
Next, go out of the sources directory and open main.swift inside the generator directory
john-williams@codermerlin:~/Experiences/CtoF/generator emacs main.swift
Remove the code between the two comment lines and insert the following code:
11 | let c = Double.random(in: 0.0 ... 100.0) 12 | insertionLines.append("let c = \(c)") 13 | let f = c * 9.0 / 5.0 + 32.0 14 | expectedStandardOutput.append("\(f)")
Save and exit emacs
Finally, go back to your main CtoF directory and execute merlin builder prepare This will prepare your challenge directories like merlin builder test would do
To test it out, run merlin builder test This will initially fail because you have not edited the prepared main.swift file yet.
Open main.siwft in emacs, and change degreesF to represent the C to F conversion Save and exit emacs, and now running merlin builder test will return a match.
Reference Solution[edit]
A reference solution is required for all challenges. It must be located in the reference subdirectory. Create the necessary solution file(s) by copying from the root of the challenge. In this case, only main.swift is needed.
john-williams@codermerlin:~/Experiences/CtoF cp main.swift reference
Modify the file in the reference directory so that it completely solves the challenge.
Be sure to be in the root directory of the challenge. Then, executing:
john-williams@codermerlin:~/Experiences/CtoF merlin builder reference
will copy this solution to the root directory of the challenge.
Verify the reference solution with:
john-williams@codermerlin:~/Experiences/CtoF merlin builder test