Merlin Builder

Within these castle walls be forged Mavens of Computer Science ...

— Merlin, The Coder

Overview

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:

1. A generator generates a problem set. The problem set serves as input to the student's program by providing:
   1. Standard input (e.g. simulates a user's keyboard input)
   2. Command line arguments
   3. 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.
   4. Expected standard output
2. 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.
3. The student's (potentially modified) program is executed using run.sh and both standard output and standard input are spooled to a file
4. A verifier compares the actual standard output with the expected standard output and determines whether or not the execution was successful

Usage

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 directory
• merlin builder prepare: Similar to the parallel merlin prepare, copies the source files to serve as a starting point for the student
• merlin builder test: Similar to the parallel merlin test, executes the generator and verifier
• merlin builder reference: Copies a reference solution from the reference subdirectory, required for all challenges
• merlin builder package: Packages the entire challenge into a single file, suitable for exchange

Getting Started

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

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

Packaging

The challenge can be easily packaged with the below command. Afterwards, the single file can be sent to  Coder Merlin™  for testing and consideration for installation.

john-williams@codermerlin:~/Experiences/CtoF  merlin builder package