Add the Libraries to your Application

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.

Getting the Source

You can either download the Soya source distribution or checkout the Soya module directly from the SVN source repository.

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
          

Signing the Assembly

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>")]

Building the Soya Distribution

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.

msbuild build.proj

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>

Building the Soya Project Web Site

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

mvn

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> -->