To install Soya on your system, you just need to Download the binary distribution and extract it into a directory on hard disk.
This will create the following directories:
soya-0.1 +-- lib // contains the Soya library and dependencies | +-- docs // contains project documentation and API docs | +-- samples // contains executables
Once you have done this, you can start creating applications that use Soya. Create a project in your favourite IDE and add a reference to the Soya.dll assembly, which can be found in the lib directory (see directory structure above).
Further, it is necessary that you include the .NET 3.0 libraries System.Runtime.Serialization.dll and System.ServiceModel.dll in your project. The latter is the library that contains WCF.
Finally, if you don't want to end up staring at a blank console window, we recommend that you set up log4n as described in the Logging Section. This step, however, is optional.
If you intend to build Soya from source, you need to have a few tools installed on your system. Which tool you will need to install depends on what part of the source you want to build:
Once you have obtained (and possibly extracted) the source, you should find a structure similar to the one below:
soya-0.1 +--src +-- lib // contains the Soya dependencies | +-- main // contains the main Soya code base | +-- main-test // contains the NUnit test cases for the Soya code base | +-- site // contains the source files for the project web site | +-- build.proj // MSBuild file for creating the Soya distributions | +-- soya.sln // Visual Studio 2005 solution file
If you don't intend to execute the Soya NUnit test cases, you must delete or exclude the entire main-test directory from your solution. Additionally, remove or comment out the AssemblyOriginatorKeyFile element in main/soya.csproj:
<!-- <AssemblyOriginatorKeyFile>..\key.pfx</AssemblyOriginatorKeyFile> -->
If you want to run the test cases, please keep reading.
Because the Soya main code is in a different assembly from the test cases, the Soya assembly declares the following attribute in its AssemblyInfo.cs. This will allow code in the Test.dll assembly to access internal members of the Soya.dll assembly.
However, for this to work, both assemblies need to have Strong Names.
Because only Soya core developers have access to the private key that is used to sign official Soya assemblies, it is necessary that users wishing to modify the Soya code base generate and use their own key.
To do so, use the Strong Name Tool (sn.exe) to generate a key pair called key.pnk in the Soya src directory (i.e. where the soya.sln file is).
sn -k key.snk
Then, extract and display the public key that you have just generated (if you want, you can delete it, as you will only need the private key for signing).
sn -p key.snk public.key sn -tp public.key del public.key
Finally, copy the public key from the output above and change the existing key defined in main/Properties/AssemblyInfo.cs.
[assembly: InternalsVisibleTo("Test, PublicKey=<Paste Your Public Key Here>")]
At the src root directory you'll find a MSBuild project called build.proj. If you enter it without any target parameters, it will build the complete Soya release distribution.
This includes compiling the C# sources, executing test cases, creating documentation and packaging everything into a source and binary distribution zip file.
Below are the targets called by Release which can also be invoked individually.
msbuild build.proj /target:Clean msbuild build.proj /target:Test msbuild build.proj /target:Site msbuild build.proj /target:Package
If you, for example, just want to compile the main code base source, change into the src/main directory and execute msbuild without any parameters.
Also, if you don't want to build the project site because you don't want to install maven, for example, just open build.proj and modify the Release target by removing the particular target.
<Target Name="Release" DependsOnTargets="Clean"> <CallTarget Targets="Build;Test;Site;Package" /> </Target>
The Soya project web site is built using Maven 2 and most of the content is written in the APT (Almost Plain Text) format. To generate the project web site just change into the src/site directory and enter
Please note that the Maven ChangeLog report requires you to have access to the Soya SVN repository. If you somehow can't access it, you can disable this report by uncommenting the following section in src/site/pom.xml
<!-- <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-changelog-plugin</artifactId> </plugin> -->