Getting started with CSO ======================== ================================================ PART 0: MINIMAL (SCRIPT-BASED) UNIX INSTALLATION ================================================ ASSUMPTIONS: A1: You have already installed Scala, and the Unix command to run it is ''scala''. A2: You know what the PATH variable signifies to whatever Unix shell you use. A3: You can download materials from the CSO site (this site) DECISION 1: Decide which folder you want your CSO materials to be placed in. (In what follows we will denote this by "$CSOROOT") Decide which folder from this site you are going to import the libraries from. (In what follows we will denote this by "$LIBRARY") STEP 0: (make the folder to contain the CSO .jar files) mkdir $CSOROOT/PUBLISH STEP 1: (Download the jar files and the scripts) Download $LIBRARY/*.jar to $CSOROOT/PUBLISH Download scripts/xso and scripts/xsoc to $CSOROOT/PUBLISH Ensure that these two files have execute permission set on them. chmod +x $CSOROOT/PUBLISH/cso* STEP 2: Arrange for the folder $CSOROOT/PUBLISH/ to be on your PATH when you are working with the scripts. This means you can use "xso" and "xsoc" as commands. =================================================================================== PART 1: SETTING UP A LITTLE CSO PROJECT (you can do this as many times as you wish) =================================================================================== DECISION 1: Decide on a root folder for your project (in what follows we will denote this by "$PROJECTROOT") STEP 1: (set up source folder and destination folder for compiled code) mkdir $PROJECTROOT/src/ mkdir $PROJECTROOT/BUILD STEP 2: (copy your source files to $PROJECTROOT/src/, or edit them in-place) Example self-contained source file: hellocso.scala import io.threadcso._ object hellocso { def main(args: Array[String]): Unit = { val program = ( proc { println("Hello CSO") } || (|| (for (arg<-args) yield proc { println(arg) })) ) program() exit() } } Notice that the file defines an object "hellocso" that has a method with signature def main(args: Array[String]): Unit = ... All CSO programs that you intend to run from the command line must be structured in this way. This goes for common-or-garden Scala programs, too. STEP 3: (change to the $PROJECTROOT folder) cd $PROJECTROOT STEP 4: (make a symbolic link to $PROJECTROOT/PUBLISH) ln -s $PROJECTROOT/PUBLISH ./PUBLISH You are now in a position to compile the source file(s), then run the resulting code. COMPILE STEP: (for the example program): xsoc src/hellocso.scala Expect to see a report of the class path and scala version 799 $ xsoc src/hellocso.scala ./PUBLISH//threadcso-1.2R5-2.12.3.jar:./PUBLISH//APP-1.0-2.12.3.jar: /Users/sufrin/Installed/scala-2.12.4 and then any warnings or error reports.... RUN STEP: xso hellocso my name is mud Here's one of the things you might be content with if you recall the nondeterminism of scheduling decisions. xso 803 $ xso hellocso my name is mud ./PUBLISH//threadcso-1.2R5-2.12.3.jar:./PUBLISH//APP-1.0-2.12.3.jar: /Users/sufrin/Installed/scala-2.12.4 Hello CSO is mud name my Once you get this far it is worth your while investigating the extent to which the two scripts can be customised. =========================================== PART 2: INTELLIJ-IDEA UNIX PROJECT WITH CSO =========================================== ASSUMPTIONS: A1: You have succeeded in performing the minimal script based installation A2: You have installed a copy of INTELLIJ with the scala plugins STEP 1: Set up a new INTELLIJ project from the INTELLIJ interface In what follows we will denote the root folder for this project by $PROJECTROOT STEP 2: (STEP 3 and STEP 4 from PART 1) STEP 3: (Add the threadcso library to your INTELLIJ project) a. Go to Project settings/Libraries tab The main menu, disconcertingly, uses "Open Module settings" to get to the project settings window. b. Hit the + over the left column (which initially will show "nothing to show") c. Now ("New Project Library") pretend you're adding a java library. d. File selection menu comes up. Select the threadcso .jar file from PUBLISH. It gets added to the right-hand pane, and the left pane gets updated accordingly. e. For each subsequent .jar you want to add (e.g. the APP jar) press + at the foot of the right-hand pane, and select the .jar file from the appropriate place. f Click Apply. Ok. Done. If you know what you are doing you can (instead) add the threadcso library as a global external library by doing much the same at the "Platform settings/Global Libraries"tab. You are now in a position to edit Scala+CSO programs. =============================== PART 3: INTELLIJ-IDEA with xso =============================== This is for those who wish to edit using INTELLIJ, but to run using xso. There is some advantage in doing this, since you can kill deadlocked or livelocked programs from the command line very easily. It's not necessarily straightforward to do this from within INTELLIJ without killing INTELLIJ itself. ASSUMPTIONS: A1: you have succeeded at parts 1 and 2. STEP 1: cd $PROJECTROOT rm BUILD ln -s $PROJECTROOT/out/production/$PROJECTNAME ($PROJECTNAME is the name of the project: usually the last name on the $PROJECTOOT path) That's all. You can now use xso as before. Bernard Sufrin (acknowledgements to Maximilian Hofer) 19th January 2018