CX10: README Simple Instruction: ===================== Run 'ant' ./bin/x10c examples/Cluster/Hello.x10 ./bin/x10 -multi 2 -Dx10.cluster.cfgfile=./etc/x10-cluster.cfg Hello & ./bin/x10 -multi 1 -Dx10.cluster.cfgfile=./etc/x10-cluster.cfg Hello In more detail: # 0 (before you start, Java 1.5, and Ant tool required) # 1. You might need to set two environment variables, JAVA_HOME, X10_PLATFORM JAVA_HOME: X10_PLATFORM: # 2. Run ant # 3. (Now you have "x10" "x10c" command under "bin/" directory) # 4. (Look for programs in "examples/" directory) # 5. ./bin/x10c examples/Cluster/Hello.x10 # 6. ./bin/x10 -multi 2 -Dx10.cluster.cfgfile=./etc/x10-cluster.cfg & # ./bin/x10 -multi 1 -Dx10.cluster.cfgfile=./etc/x10-cluster.cfg # # (modify x10-cluster.cfg if you want, and copy it to your home directory, # then you can avoid "-Dx10.cluster.cfgfile" passing every time. Just do: # ./bin/x10 -multi 2 & # ./bin/x10 -multi 1 ) # # (7). see below for instruction of using "bin/cx10run.sh" when you # want to run cx10 on multiple machines. (it can be used to lauch multiple # VMs on the same machine, too) Detailed Instruction: ---------------------------------------- 1) Extraction 2) Setup 3) Running it - TCP port number 4) Check out from CVS 5) Misc: scripts, single VM compatibility ---------------------------------------- First, you need working installations of ant and Java 1.5. On Windows, you need cygwin. 1) Extraction Extract cluster_x10.zip using your favorite decompression utility. Set your JAVA_HOME and X10_PLATFORM variables appropriately. (NB: Windows user, you have to set these two environment variables from Windows (not within your shell), i.e., right click My Computer -> Properties -> Advanced -> Environment Variables. The reason is that when 'ant' is run from Cygwin, it's run as a native Windows process. See 'ant' documentation.) Change to the cluster_x10 directory. Run "ant". Change to the cluster_x10/test directory. From within bash, run compile.sh. This will build all of the tests we have been using to drive the implementation. --------- Sidebar: compilation --------- You use x10c to do this, just like javac. /x10.common/bin/x10c .x10 ---------------------------------------- 2) Setup At this point you will have the commands x10c and x10 under cluster_x10/bin/; these can be used just like java and javac. You need a configuration file called "x10-cluster.cfg". The details of this file are presented below. There is an example under cluster_x10/etc/. You can edit that file to use the hostname of your machine. The default is localhost, which should be fine for testing purposes. There are two ways to get x10 to recognize this file. You can pass it as an argument to x10, by invoking x10 with: x10 -Dx10.cluster.cfgfile= You can also put it in your home directory. This is ~ under Linux/UNIX, and typically "C:\Documents and Settings\" in Windows. --------- Sidebar: x10-cluster.cfg --------- The file has lines of the form: > An example file would look like the following: # --begin-- 1, localhost, 0 1 2, localhost, 2 3 # --end-- This states that there are going to be two VMs, both on localhost. Places 0 and 1 will be in the first VM, and places 2 and 3 will be in the second. NB: the standard way to configure single-VM X10 is unchanged, i.e., the default MAX_PLACES is 4, and if you want to change it, you want to edit file /etc/standard.cfg, or pass the file name through -Dx10.configuration= when running x10. -------------------------------------------- 3) Running it. First, pick a multi-placed X10 program. The ones bundled with this release (see /examples) were taken from the examples in x10.common module, with some bugs fixed: Then, you need to start the virtual machines: x10 -multi So, if you want to use everything as we packaged it, and you are in the cluster_x10/test directory, and you want to run RandomAccess_int, you would type: ../bin/x10 -Dx10.cluster.cfgfile=../etc/x10-cluster.cfg -multi 2 RandomAccess_int & ../bin/x10 -Dx10.cluster.cfgfile=../etc/x10-cluster.cfg -multi 1 RandomAccess_int You need to start the VM that maps to place 0 (per x10-cluster.cfg) last, because it does some extra coordination. That is VM 1 in our example. When the VMs that do not map to place 0 start up, they will block until the VM that maps to place 0 starts. Therefore, you must start them in the background or in different windows. Normally all VMs will exit on program finish, but in case of unexpected failure, you might need to kill the VM in the background. This can be done with the Task Manager on Windows, or via the kill command. - TCP port number By default, CX10 VMs listens at port: 30003 + current place id. This should normally suffice. In case, this port number is used by other processes on some node, you can specify a different "port base" than 30003 when you run 'x10'. For example: -----------side bar: specify a different TCP port to use -------- x10 -Dx10.cluster.portbase=4000 .... It's important that all 'x10' are launched with the same portbase number, since each VM relies on this number to find VMs on different nodes. ----------------------------------------------------------------- 4) Instructions if you want to check out from CVS, compile and build yourself. You need to check out the CLUSTER branch from CVS. Check out lpg, x10.common, x10.compiler, polyglot2 and x10.runtime. Build all of the projects, in the order of lpg, polyglot2, x10.runtime, x10.compiler and finally x10.common, using 'ant' tool. This will create the commands x10c and x10 under x10.common/bin. Now you can run x10 and x10c as shown above. 5) Misc There is an sample script for running a X10 program on different physical machines in a loosely coupled environment. See cluster_x10/bin/cx10run.sh. But default, it takes two arguments, a cluster configuration file and the main class name. It will try to "ssh" to the machines in the file and start the VMs. It is tested on Linux platforms. For example: ------------- using cx10run.sh script ------------ ~> /bin/cx10run.sh -f x10-cluster.LAN RandomAccess_int ~> cx10run.sh -h Inside x10-cluster.LAN file, you specify the place to machine mapped as before. --------------------------------------------------- The 'x10' command can also be used to fall back to the single VM behavior. For this you just need to run x10 without the cluster specific command line options like "-multi", "-Dx10.cluster.cfgfile". For example, you would ran RandomAccess_int like this: ------------- run cx10 in single VM mode ------------ ~> /x10.common/bin/x10 RandomAccess_int ------------------------------------------------------ This is convenient for checking correctness when running cx10 on multiple VMs. We made a best effort to make cx10 backward compatible. For more please check out ./doc directory or visit: http://www.cs.purdue.edu/~xinb/cx10 Please send you comments to Bin Xin xinb@cs.purdue.edu