billbarnhill / bcpm Goto Github PK

Battlecode (MIT 6.470) package manager.

USAGE

1. Make sure you're using the latest tool version.

    bcpm self

2. Install the Battlecode distribution. Later, use the same command to update the distribution.

    bcpm dist

3a. Check out a player repository and set it up for development.

    cd ~/workspace  # Your Eclipse workspace.
    bcpm install [email protected]:six370/yield.git

After executing the commands above, import the project into Eclipse
(File > Import > Existing Projects into Workspace).

3b. Create a blank player.

    bcpm new team1337
     
If you go this route, you will have to create the git repositories yourself, and push them.

4. Confirm that the player is installed.

    bcpm list
    bcpm ls

5a. Switch between the 2D and the 3D client.

    bcpm set client3d on
    bcpm set +client3d
    bcpm set client3d off
    bcpm set -client3d

5b. Turn the client sound on or off.

   bcpm set +sound
   bcpm set -sound

6. See all the maps in the distribution.

    bcpm listmaps
    bcpm lsmaps

7. Run a game against some other player code.

    bcpm match yield team000 venice

    # The following command runs the match right away, for maximum enjoyment.
    bcpm livematch yield team000 venice

7b. Game too slow? Increase the JVM memory.

    bcpm set vm_ram 1024

8. Run a debugging game against some other player code. Debugging games us use bcpm configuration settings instead of production defaults.

    bcpm debugmatch yield team000 venice

9. Set the number of simultaneous matches. Match the number of physical cores you have.

    bcpm set match_threads 2

10a. Run a duel between 2 players on multiple maps.

    bcpm duel yield team000
    
    # The following command restricts the duel to a subset of maps.
    bcpm duel yield team000 venice fortress

10b. Pit a player against other players you have installed.

    bcpm pit yield team000 team001
    
    # The following pits against all other installed players.
    bcpm pit yield
    
10c. Rank players by their total scores in all possible pairwise duels.
 
    bcpm rank yield team000 team001
    
    # The following ranks all installed players.
    bcpm rank
 
11a. Show all settings.

    bcpm config
    
11b. Change debugging settings

    bcpm set +noupkeep
    bcpm set -noupkeep
    bcpm set +debugcode
    bcpm set -debugcode
    bcpm set +breakpoints
    bcpm set -breakpoints
    bcpm set debuglimit 1000000  # Maximum number of bytecodes per round in debug_ methods.

12. Run the player's test suite.

    bcpm test yield

13. Run a single test case in the player's test suite.

    bcpm case yield win_vs_yield
    
    # The following command runs the first match right away, for maximum iterating speed.
    bcpm livecase yield win_vs_yield

14. Replay the last match ran in a test.

    bcpm replay
    
15. Copy a distribution map into the test suite, for customization.

    bcpm copymap venice

16. Remove the installed player. (removing the project folder is not enough!)

    bcpm uninstall yield
    
17. Create a new player from an existing template.

    bcpm copy myplayer [email protected]:six370/yield.git
    bcpm copy myplayer [email protected]:six370/yield.git branch_or_tag_name

You'll need to import the project into Eclipse, and setup a git repository for the player.

18. If bcpm crashes or you abort it, you'll need to clean up the temporaries left behind.

    bcpm clean
  
19. Use directed find/replace to unroll loops.

    bcpm regen bcpm regen src/yield/test/stubs/LoggingStubs.java
    
20. After winning the competition, remove the players and distribution. Commit and push first!

    bcpm reset


TESTING

The test cases are .rb (Ruby) files in the 'suite' directory. The following example showcases the
functionality available in a test suite. The suite DSL slightly resembles rspec.

    # Set the side of the tested player in future matches.
    side :b

    # Set the opponent for future matches.
    vs 'yield'
    
    # Set the map for future matches.
    map 'venice'

    # Use a custom map from suite/maps.
    suite_map 'venice2'
    
    # Disable energon draining. :upkeep is a synonym for 'bc.engine.upkeep'.
    option :upkeep, false
    
    # Replace a .java file in the player under test with a .java file in the test suite.
    # Both names are automatically prefixed with the team package ('yield.' in this case).
    replace_class 'RobotPlayer', 'test.players.TestRobotPlayer'
    
    # Re-route all calls that look like target.canMove(...) to
    # yield.test.stubs.LoggingStubs.canMoveStub(target, ...)
    stub_member_call 'canMove', 'test.stubs.LoggingStubs.canMoveStub'
    
    # Re-route all calls that look like target.wantStubbing(...) to
    # yield.test.stubs.LoggingStubs.wantStubbingStub(...)
    stub_static_call 'wantStubbing', 'test.stubs.LoggingStubs.wantStubbingStub'
    
    # Replace the code marked with Stubs.canMove.logo in yield.LoggingStubs with the code marked
    # Stubs.canMove.logoSource in yield.test.stubs.LoggingStubs
    replace_code 'LoggingStubs', 'Stubs.canMove.logo',
                 'test.stubs.LoggingStubs', 'Stubs.canMove.logoSource'
    
    # Run a test match to check some conditions.
    match do
      it 'must win in any way' do
        should_win
      end
    
      it "shouldn't leak exceptions" do
        should_not_throw
      end
      
      it 'should stub the member call' do
        should_match_unit_output(/This should show up/)
      end
      
      it 'should stub the static call' do
        should_match_unit_output(/wantStubbing\: this (.*) be printed/) do |unit, match|
          fail 'Static call not stubbed' unless match[1] == 'should'
        end
      end
      
      it 'should fail' do
        fail
      end
    end
    
    # Reset energon draining option to its default value.
    option 'bc.engine.upkeep', nil

To prevent infinite recursion, stubbing should be disabled in the actual stubs. To prevent
compilation errors, stubbing should also be disabled on the first line of the stubbed method's
definition. The stub implementation below demonstrates the syntax for stubbing and code replacement.

    package yield.test.stubs;
    
    import battlecode.common.Direction;
    import battlecode.common.RobotController;
    
    public class LoggingStubs {
      //$ -stubs
      public static final boolean canMoveStub(RobotController target, Direction where) {
        boolean returnValue = target.canMove(where);
        //$ +mark: Stubs.canMove.logo
        System.out.println("This should not show up");
        //$ -mark: Stubs.canMove.logo    
        System.out.println("canMove(" + where.toString() + ") -> " + returnValue);
        return returnValue;
      }
      //$ +stubs
    
      public static void markTest() {
        //$ +mark: Stubs.canMove.logoSource
        System.out.println("This should show up");
        //$ -mark: Stubs.canMove.logoSource
      }
    }

The code patching directives use very simple implementations based on file copying and regular
expressions. Following these best practices should help avoid broken builds:

  * Use Eclipse's "Organize imports" feature to achieve the item below:
  * Class names should be unqualified, and imports should use fully qualified names.
  * Use the same class name (but different package names) in replace_class.
  * A replace_class source class should only depend on classes in other packages.


DIRECTED FIND/REPLACE

bcpm regen reads one or more source files and discovers tagged source blocks, then replaces matching
target blocks while renaming tokens. The example below shows the syntax.
    
    System.out.print("Should show numbers 1-3 and letters A-C: ");
    //$ +gen:source Numbers A 1
    System.out.print("A 1 ");
    //$ +gen:off
    // This used to be System.out.print("A 1");
    //$ -gen:off
    //$ -gen:source
    //$ +gen:target Numbers B 2
    //$ -gen:target
    //$ +gen:target Numbers C 3
    System.out.print("A 1 ");
    //$ -gen:target


INSTALLATION

On Ubuntu:
   
    sudo apt-get install ruby-full rubygems
    sudo gem install rubygems-update
    sudo `gem env | grep 'EXECUTABLE DIRECTORY' | ruby -e "puts gets.split(': ', 2).last"`/update_rubygems

On OSX:

    Get git from http://code.google.com/p/git-osx-installer/

On Windows 7+:

    Get git from http://code.google.com/p/msysgit/downloads/
    Get ruby 1.8.7 (add it to your path) from http://rubyinstaller.org/downloads/
    Get ant from http://code.google.com/p/winant/

On everything (skip the 'sudo' prefix on Windows though):

    sudo gem install rake echoe
    git clone [email protected]:six370/bcpm.git
    cd bcpm
    rake install

You'll need an administrative shell on Windows.