Compilers
Output files

By default, the Sphere Engine Compilers returns the following streams as part of the submission execution results (see also the related entry):

• standard output stream (stdout),
• standard error stream (stderr),
• compilation error stream (cmpinfo).

If you need to capture custom files generated during the runtime of the end-user's program, you can do so by providing a list of file names through the output_filenames parameter in the POST /submissions API method. Specifically, you can achieve this as follows:

curl -X POST \
    -F "compilerId=116" \
    -F "source=@prog.py" \
    -F "input=input data" \
    -F "output_filenames=custom_file_1.png;custom_file_2.log" \
    "https://<customer_id>.compilers.sphere-engine.com/api/v4/submissions?access_token=<access_token>"

When using this feature, the captured files will be stored in the stdout stream. In this context, the stdout will always be a tar.gz compressed archive containing all the files specified in the output_filenames parameter. Additionally, the archive will include the standard output data as a separate file with the predefined name SE_STDOUT.

Specification of the output_filenames parameter

There are two methods for providing a list of filenames to the POST /submissions API method:

• as a single string containing a semicolon-separated list of filenames (or relative paths),
• as an array of filenames (or relative paths).

The filename (or relative path) is always relative to the location of the end user's program and must refer to a regular file (i.e., not a directory or any other type of resource).

Specification of the stdout archive

The archive retains the same file hierarchy as present during the execution of the end-user's submission: top-level files are positioned at the root of the archive, while nested files maintain their respective nested structure within the archive.

Example

Let's consider an example using the following value for the output_filenames parameter:

custom_file_1.txt;custom_file_2.dat;custom_dir/custom_file_3.log

And suppose the end-user's program is written in Python and looks like this:

print('the beginning of the content of the standard output stream')

with open('custom_file_1.txt', 'w') as f:
    f.write('content of the first file')

with open('custom_file_2.dat', 'w') as f:
    f.write('content of the second file')

print('the middle of the content of the standard output stream')

os.mkdir('custom_dir')

with open('custom_dir/custom_file_3.log', 'w') as f:
    f.write('content of the third file, which is located inside a directory')

print('the end of the content of the standard output stream')

After the submission is executed, the stdout stream will contain a tar.gz archive with the following structure:

.
├── SE_STDOUT
├── custom_file_1.txt
├── custom_file_2.dat
└── custom_dir
    └── custom_file_3.log

Upon extracting the archive, you will find the following files:

SE_STDOUT

the beginning of the content of the standard output stream
the middle of the content of the standard output stream
the end of the content of the standard output stream

custom_file_1.txt

content of the first file

custom_file_2.dat

content of the second file

custom_dir/custom_file_3.log

content of the third file, which is located inside a directory