From 36f47b618c222643b4edcb281c55a0b159931b16 Mon Sep 17 00:00:00 2001 From: Daniel Axtens Date: Tue, 14 Sep 2010 22:59:24 +0800 Subject: [PATCH] C documentation --- src/link/C/README | 29 --------------- src/link/C/README.txt | 82 ++++++++++++++++++++++++++++++++++++++++++ src/link/C/WINDOWS.txt | 38 ++++++++++++++++++++ src/link/C/c_agents.py | 2 +- 4 files changed, 121 insertions(+), 30 deletions(-) delete mode 100644 src/link/C/README create mode 100644 src/link/C/README.txt create mode 100644 src/link/C/WINDOWS.txt diff --git a/src/link/C/README b/src/link/C/README deleted file mode 100644 index ad894a7..0000000 --- a/src/link/C/README +++ /dev/null @@ -1,29 +0,0 @@ -Welcome to the C SDK and link library. - -If you want to enter in C, you've come to the right place. - -== Compiling and testing the sample bots == - -Run "make" in this directory. To include them in the - -== Making your own agent == -See wiki page. - -Also, use the link/bundle-agent.sh shell script - it will take your agent file -and make a python module that you can include. - -= Testing your own agent = -Edit src/simulate.py. -Your agents live in link.C.c_agents -Add them to Agents to get them to do battle. - -For example, this code imports c_angel, c_lucifer, c_streetfighter and -c_wash, as well as the python sample agents, and then battles c_lucifer, -python Wash, c_streetfighter and c_angel. It goes at the top of simulate.py. - -# Import and add your agents here: -from link.C.c_agents import c_angel, c_lucifer, c_streetfighter, c_wash - -from SampleAgents import Angel, Lucifer, Dummy, Wash, Streetfighter -Agents = [c_lucifer, Wash, c_streetfighter, c_angel] - diff --git a/src/link/C/README.txt b/src/link/C/README.txt new file mode 100644 index 0000000..e93d251 --- /dev/null +++ b/src/link/C/README.txt @@ -0,0 +1,82 @@ +Welcome to the C SDK and link library. + +If you want to enter in C, you've come to the right place. + +== Compiling and watching the sample bots in 2 easy steps == + +Run "make" in this directory. [NB: this document assumes you use Linux +or Mac OS X. If you use Windows, see WINDOWS.txt for instructions.] + +Go to the src/ directory and run "./simulate.py -v -a CSampleAgents". + +== Making your own agent with C in 11 easy steps == + +0. Flick through the documentation. + +1. Pick a name for your agent. Make sure the name is a valid identifier +in both C and Python. Be original. Names do *not* have to be prefixed +with "c_" + +2. Flick through the sample agents in the agents directory. Pick a +sample agent to copy-paste (so you don't have to type out the function +definitions). + +3. Copy the sample agent code into a new file in the "agents" directory. +Make sure the file name matches the new agent name. The makefile will +automatically compile your new agent when you run "make". + +4. Create a python wrapper for your agent, by copying one of the sample +agent definitions in c_agents.py and using the name of your agent. + +5. Create an arena in which your agent can battle: + + 5.1. open arenas/MyArena.py + + 5.2. add "from link.C.c_agents import " + + 5.3. modify the "Agents =" line to include your agent, and take out +any agents you don't want to battle. + + 5.4. to see how to import the C sample agents, see CSampleAgents.py. + +6. Watch your agent in action: ./simulate -v -a MyArena + +7. Oh no, my agent dies very quickly: what's going on? + + 7.1 insert debugmsg() statements in your C program. + + 7.1.1 debugmsg() is like printf - see c_link.h for an example. + + 7.1.2 in Initialise(), save the name that's passed to you so +that you can uniquely identify your agent when you're printing debug +statements. + + 7.2 Run "./simulate -v -n 1 -a MyArena" to start with only 1 of each +agent. + + 7.3 Change the agents against which you're battling in MyArena.py so +that you have a predictable opponent. + + 7.4 Edit conf.py, and set DEBUG=True. Don't forget to reset it when +you're done. + + 7.5 Read doc/UNSUPPORTED.txt to see how to interact directly with +your agent. You can then invoke your agent from the command line +(for example "./link/C/agents/c_angel") and see how it responds. + +8. Once your agent works to your satisfaction, try it both on short and +long durations (100 and 1000 rounds: see MAX_ITERATIONS in conf.py) + +9. If the rolling scoreboard has been opened on progcomp.ucc.asn.au/, +submit it there! Otherwise, sit tight. + +10. Watch its progress on the scoreboard and adjust your strategy +accordingly. + +=== OTHER IMPORTANT NOTES === + + * Static storage *is* *considered* *cheating*. You must *not* attempt +to communicate between instances of your agent in any way other than by +sequences of moves. + + * Obfuscated code is bad. Don't do it. diff --git a/src/link/C/WINDOWS.txt b/src/link/C/WINDOWS.txt new file mode 100644 index 0000000..d167e2b --- /dev/null +++ b/src/link/C/WINDOWS.txt @@ -0,0 +1,38 @@ +WINDOWS.txt: Notes towards using C under Microsoft Windows. + +Whilst we are committed to supporting Windows, unfortunately Windows +support is not complete at this point. Whilst there is nothing in the +code that is specifically incompatible with Windows, it is entirely +untested, and there may be a number of tweaks that Windows users will +have to make in order to compete. + + = Options for Windows Users = + + - Install a *nix compatibility layer, such as Cygwin or MinGW, which +will allow you to develop as if on Linux. This is *by* *far* the +simplest route: everything should, in theory, just work. However, it's +untested. + + - Attempt to use native Windows tools. If you choose to go down this +path, note the following: + - agents are compiled by linking c_link together with the agent +source. + - c_agents would need to be modified to use windows style paths +instead of POSIX paths. + - The externAgent wrapper may need to be tweaked. + +Either way, be aware that the supervisor will spawn a *lot* of processes +- up to 255 child processes. How Windows will cope with that, is, as +mentioned before, totally untested. + + = Alternatives = + +There are some alternatives to development in Windows that may be open +to you: + - If you are a CS or Engineering student at UWA, use Mac or Linux +machines in the CS labs. + - If you are a UCC member, use either our Mac or one of the Linux +machines. + +These environments, if available to you, are preferable to development +on Windows. diff --git a/src/link/C/c_agents.py b/src/link/C/c_agents.py index aabdc23..ed461b5 100644 --- a/src/link/C/c_agents.py +++ b/src/link/C/c_agents.py @@ -1,5 +1,5 @@ # add your agents to this file by copying the definition and adjusting -# you then need to modify simulate.py +# you then need to make sure there's an arena that imports your agent from link.cAgent import cAgent -- 2.20.1