saradindusengupta / codejam-commandline

Automatically exported from code.google.com/p/codejam-commandline
Apache License 2.0
0 stars 0 forks source link

GCJ Commandline submit tool, v1.0-beta4 Copyright 2010 Google Inc. All Rights Reserved.

Download and submit tool for the Google Code Jam

TABLE OF CONTENTS:

  1. Disclaimer
  2. Prerequisites
  3. Basic usage a. Configuring the system b. Initializing the contest c. Downloading an input d. Submitting a solution e. Checking your status f. Cleaning the contest
  4. Configuration files
  5. Executable files a. Contest crawler b. Login agent c. Input downloader d. Solution submitter e. Contest cleaner

  1. DISCLAIMER

GCJ Commandline submit tool, v1.0-beta3 Copyright 2010 Google Inc. All Rights Reserved.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.


  1. PREREQUISITES

To install this software, just copy these files into any folder and execute the python scripts from the main folder (the one that contains this file).

To run the scripts, you will need Python 2.6, which can be downloaded from http://www.python.org/download/releases/. This was developed and tested using Python 2.6.5, so we recommend using 2.6.5 or later.


  1. BASIC USAGE

To use this tool, open a terminal in the main folder (the one that contains this file). The scripts in this directory expect to be run from this directory, otherwise, they will not find the configuration files in the config/ directory.

2a. Configuring the system

Before attempting to run a script included with this software, you should configure the system by writing some needed information in the user configuration file, located at config/user_config.py. This file is formatted as a Python dict structure, but a basic one is be included with this software. Three values are needed to run the software:

Look at Section 3 for more information about these and many more configuration parameters.

2b. Initializing the contest

The first step to use this software is initializing the contest. To do this you have to specify the contest id, which can be found in the dashboard URL for that contest. For example, for the GCJ 2010 Qualification Round the dashboard URL is:

http://code.google.com/codejam/contest/dashboard?c=433101

so you can initialize the contest executing:

$ ./gcj_init_contest.py 433101

During this step, the software logs into Code Jam servers (it may ask for your password) and extracts information from the contest, including problem ids, names and the middleware tokens required to transfer information.

Then, all this information, including the login cookie and the information in the user configuration file, is stored in the current configuration file (found at config/current_config.py).

If you don't specify a contest id for this script, it will attempt to initialize the tool for the current contest. If no contest is running it will print an error message.

NOTE: Your password is not stored in the current configuration file if you did not entered it in the user configuration file.

2c. Downloading an input

Once you have implemented a solution and think you got it right, you may download an input file using the gcj_download_input.py script. This script receives the problem letter (A, B or C for the GCJ10 Qual), the I/O set name and an id to differentiate it from other attempts.

If a problem has only one small I/O set it will be called "small", but if it has multiple small I/O sets they will be called "small1", "small2", "small3", and so on (all quotes for clarity). Large I/O sets are named in the same way.

For example, to download a small input for the problem A, Snapper Chain, you can execute:

$ ./gcj_download_input.py A small 0

which will download the input file and store it in source/A-small-0.in. Now it is time to run your solution and generate the output file.

NOTE: Downloading an input file twice in the same attempt will just redownload the same input file if its timer has NOT expired. Otherwise, it will download another input and start another attempt for small I/O sets. However, if this is the case it will ask for confirmation from the user.

2d. Submitting a solution

After running your solution and generating the output, it is time to submit the output file with the source files using the gcj_submit_solution.py script. This script receives the problem letter, the I/O set name and the id used when the input was downloaded. See section 2c for I/O set naming.

For example, to submit the solution for the small I/O set of problem A, Snapper Chain, you can execute:

$ ./gcj_submit_solution.py A small 0

which will submit the file source/A-small-0.out as the answer and source/A-small-0.cpp as the only source file. If you want to add extra source files, you may use the -a flag as many times you need. For example, if you want to submit two extra files called library.cpp and template.txt you can execute:

$ ./gcj_submit_solution.py -a library.cpp -a template.txt A small 0

which will submit the file source/A-small-0.out as the answer and source/A-small-0.cpp, library.cpp and template.txt as the source files. If you add a directory using the -a option, the program will compress it into a zip file before submitting it.

After submitting the file, the Code Jam server will answer with a message string. The most important values are:

2e. Checking your status

During the contest you can check your status by using the gcj_get_status.py script, which will show you your current rank, number of points, time at which each input was solved, number of wrong attempts per input and remaining time for current attempts.

To run this script you should execute:

$ ./gcj_get_status.py

which will show an output like this one:

Rank: 194 (66 points) Problem: Snapper Chain small: 00:15:16 (2 wrong tries) large: 00:19:11 Problem: Fair Warning small: --:--:-- (1 wrong try) << 2:31 left large: --:--:-- Problem: Theme Park small: 01:42:45 large: 01:47:18 << 6:38 left

2f. Cleaning the contest

After the contest is over, you can clean all contest-related information using the ./gcj_clear_contest.py script, which receives no parameters. This script will not delete your source code, input or output files.


  1. CONFIGURATION FILES

This tool needs one configuration file to run, which can be located at config/user_config.py. This file is formatted as a python dict structure and may have the following keys:

All these values (with the exception of 'host', 'user' and 'source_names_format') can be overriden in the scripts by using command line options. When these values are specified on the command line, the values in the configuration files and the default values are ignored.

For the input, output and source format the final filename is generated using the Python str.format() function.

If you want to change the path of the configuration file, look at the lib/constants.py file and change the respective variables. Remember that those paths are relative to the current directory, not to the lib directory. You could also use absolute paths or use the placeholder '{base_dir}' (quotes for clarity); this placeholder will be substituted by the directory where the tool is in the filesystem.

IMPORTANT: Scripts stores information from the current contest along with the user information in the current configuration file (config/current_config.py). However, any change you make in the user configuration file will be recognized by the scripts, even if the current configuration file is not updated. This implies that the user should update their information in the user configuration file, otherwise the scripts will not see the change.


  1. EXECUTABLE FILES

This tool is composed by four executable scripts, one to initialize the tool for a contest, one to download inputs, one to submit solutions and finally one to login in the Google servers, just in case the authentication cookie becomes invalid.

All scripts provide a --version and a --help options. These options will show the current tool version and a list with all the possible options for the script, including a brief description of each one.

All scripts might require your Google password if you do not specify it in the configuration file. Another option is to pass the password using the option --passwd, just be careful that specifying the password this way will be visible in your screen and will be stored in the commands history.

The scripts to download input and submit outputs support a --login option; if this option is specified the current login cookie will be ignored and a new one will be requested. Also, if the cookie has expired the scripts will automatically try to renew it. Beware that this might cause the executables to ask for your password. Also, these scripts ask confirmation from the user before downloading an input that will start a new timer and before resubmitting a solution for a large input. These confirmations can be skipped by passing the --force option.

4a. Contest crawler

This script is the gcj_init_contest.py script and receives one optional positional argument which is the contest id (see Section 2b for instructions on how to retrieve a contest id), that is used to retrieve the important information of the contest, i.e., number of problems, middleware authentication tokens, problem ids, etc.

If no contest id is specified in the arguments, this script will retrieve the id of the current contest and initialize the tool for it. If there is no running contest an error message will be shown to the user.

This script should be run once before each contest, so the correct information is retrieved. Otherwise, all other scripts might fail because no contest data will be found.

4b. Login agent

This script is the gcj_renew_login.py script and receives no positional arguments, and will renew the login cookie in the current configuration file with a new one.

This script should not be used under regular operation, this is just included in case your login cookie expires or becomes invalid during a contest.

4c. Input downloader

This script is the gcj_download_input.py script and receives three positional arguments, the problem letter, the input size ('small' or 'large') and a submit id. The problem letter and the input size are always converted to uppercase and lowercase before using them, respectively, but the id is case-sensitive.

This script downloads the specified input and stores it in a file inside the data directory. However, the flags --data-directory and --input-name are provided to override the default values and the ones in the configuration files.

4d. Solution submitter

This script is the gcj_submit_solution.py script and receives three positional arguments, the problem letter, the input size ('small' or 'large') and a submit id. Similar to the input downloader, both the problem letter and the input size are converted to uppercase and lowercase before using them, respectively, but the id is case-sensitive.

If a directory is specified as an output file, this executable will zip it into a file before submitting, so the whole folder can be sent to the server.

By default this script submits the specified output files along with the additional default source files specified in the configuration file. However, this script provides many options to alter its default behaviour:

4e. Contest cleaner

This script is the gcj_clear_contest.py script and receives no positional arguments. When this script is executed all contest-related information will be removed from the system, which does not include your source code, input or output files.