# How to build and debug P4Connect.

## Prerequisites: 

1. Visual Studio:  
You need to use Visual Studio 2013, Visual studio 2013 community edition is now free download and use. 
Download it from http://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx

2. The UnityVS plugin for Visual studio 2013 Download it from http://www.unityvs.com 

3. The source for P4Connect is available by Perforce connection to workshop.perforce.com:1666
   I recommend that you create an account on the workshop, and then branch from `//guest/perforce_software/p4connect` into 
a personal development branch.   I used `//guest/norman_morse/dev/p4connect`.  
Do all your development on your own development branch, until your code is stable, and you are ready to generate a change request.

If you are new to Perforce, or need a refresher, you might find the following articles helpful in getting you set up with P4 and p4V:

* http://www.perforce.com/perforce/doc.current/manuals/intro/

* http://www.perforce.com/perforce/doc.current/manuals/p4v-gs/index.html

## Preparation:

### Creating a sample Unity project to test P4Connect.
Create a sample Unity project to be used while debugging P4Connect.  I have created a project for Visual Studio 2013, 
you can use that if you wish...

    .\p4connect\UnitySampleVS2013.sln
 
This solution contains UnityVS assets and includes customized UnityVS solutions and projects.

More instructions about how to set up the sample project for debugging a Unity DLL are here:
http://unityvs.com/documentation/dll-debugging/

The UnityVS plugin will generate a solution file which will "wrap" the Unity project.  

### Configuring the AssetTarget.txt files 

*IMPORTANT!!!*  Two AssetTarget.txt files need to be customized to tell visual studio where to copy the generated files.
Each of these files contains the relative path (relative to the location of the AssetTarget.txt file) for where
built assets get copied.  These files are used in both Windows and OSX builds, and must use Backslash characters for directory separators.

Remember that Unity Projects are version specific, so you will need to use a different AssetTarget.txt configuration to select projects which match the Unity Version.

So to debug P4Connect while running Unity in the sample project at ...\UnitySampleVS2013 

    .\src\P4Connect\AssetTarget.txt should contain "..\..\UnitySampleVS2013\Assets"
    .\src\P4Bridge\AssetTarget.txt  should contain "..\..\UnitySampleVS2013\Assets"

both "AssetTarget.txt" files should contain the relative path ..\..\UnitySampleVS2013\Assets

If you need to change the AssetTarget.txt files and they exist in Perforce, you should check 
them out first.

### Adding P4Connect projects to the UnityVS Solution

If you add the P4Connect projects to the UnityVS Solution, it will allow you to build from source, 
run in Unity and debug in Visual Studio.

Project and Solution files are marked with a ".vs13" extension. This specifies which version of visual 
studio is needed to open the project.   For the purposes of this document I will assume you are using Visual Studio 2013.

The projects which need to be included to build and debug P4Connect are: 

    .\P4Bridge\p4bridge\p4bridge.vs13.vcxproj
    .\PBridge\p4api.net\p4api.net.vs\13.csproj
    .\P4Connect\P4Connect.vs13.csproj
    .\P4Connect\P4ConnectTest.vs13.csproj    (if building DEBUG)

## Debugging P4Connect:

### Problems initializing Perforce

Sometimes, After a rebuild of assets or an initial install, a Perforce server is not found. 

First try disabling and then re-enabling Perforce in the Perforce Settings Window ("Edit -> Perforce Settings")

If you are still having issues,  try opening your Perforce project in P4V and make sure that the files appear in your workspace where 
you expect.  If so, use the P4V settings for P4HOST, USER and WORKSPACE to configure P4Connect using a P4CONFIG file.

Manually inspect your Project Window in unity, and make sure the required DLL's or dylibs are in the right architecture directories.

Also, if there is an "Config.Asset" file in Assets/P4Connect/Editor,  try removing it, and then reconfiguring.

Under OSX, you may need to restart Unity a couple of times to get the P4 Settings dialog to show up.  
During one of the reboots, it will inform you that it has copied the .dylib file to the project root.
If you have problems, try removing the .dylib file in the root, then restarting Unity, which should trigger the copy.

### Dealing with strange errors involving solution and project files.

While setting up P4Connect with a new project, you might want to make sure that all the UnityVS.*
project and solution files in the project are writeable by checking them out from Perforce if they
are stored there.   

The "Include Solution Files" and "Include Projects Files" options work OK if the project and solution 
files already exist and are under Perforce control.  If not, turn these options OFF.

Same thing goes for the "Integrate with UnityVS" option.

### Using a localhost server for P4Connect testing

If you are working on the P4Connect code, using a connection to workshop, it can be very confusing.
This is because P4Connect will detect that you are connected to the workshop and try to add your 
development project to the workshop.

It is much easier if you can create a localhost Perforce server, and have P4Connect use that server instead
of trying to store game assets in the workshop P4Connect repository.

You can do this by using the P4CONFIG option and creating a P4CONFIG file in the root of the 
Unity Game directory.   In my case, P4Connect is attaching to a server on localhost:1666, while 
the source is still being managed from the workshop.

For more information about P4CONFIG, look here: 
http://www.perforce.com/perforce/doc.current/manuals/cmdref/P4CONFIG.html

### Additional logging options

Logging is handled by the log4net library.   The configuration is hard-wired into the source, but can be customized by creating 
an XML configuration file and storing it as .../Asset/P4Connect/Editor/log4net.xml

In the C++ Bridge code, you can add debug statements using the LOG_XXX statements defined in P4BridgeServer.h
These statements will be picked up by log4net.

In the P4 Settings dialog you can select what levels of log entries get echoed to the console, or disable logging entirely
This is useful because you get a stack trace as a side effect of a console log line.

### Exception Handling in P4Connect

p4Connect uses a customized version of the P4API.NET api to run.  The P4Connect version of P4API.NET has some changes needed to support OSX,
most importantly, although WINDOWS uses Structured Exception Handling, OSX can not.   For OSX the `__try` and `__except` keywords are 
actually macros which make the line into a comment.

What this means is that any code within an `__except` block will <b>ALWAYS BE RUN IN OSX</b>,  and since this is error handling code, bad things will happen.  
So the rule is,  Any code in a `__finally` block must have it's content wrapped with `#ifdef _OS_NT` 

For this reason, the P4Connect is currently limited to single threading under OSX.  It should be possible to do a PThreads implementation to match the Windows Locking 
code in P4API.Net, but it isn't necessary since Unity is still single threaded.

## Building P4Connect

By default, all the build processes copy files to the appropriate location under the AssetRoot.  Make sure that 
your AssetRoot is correctly set.   Everything can be built using "DEBUG", but these instructions assume "RELEASE".

Having the output copied to AssetRoot is nice, it allows you to run and debug code under development by just refreshing 
Unity after a build.  However, this is only good for debugging, you will need a .unitypackage if you want to give this 
other users.

All .NET assemblies live in Assets/P4Connect/Editor    And native mode DLL's live in architecture specific directories 
    Assets/P4Connect/Editor/x86  
    Assets/P4Connect/Editor/x86_64.

To build an entire copy of P4Connect you need to do several builds and then load them all up in Unity, so you can export a .unityasset package.

1. In Visual Studio, check your build configuration, make sure that all settings are "x86" and that the p4bridge project is selected.
   Then build all   This will create all .NET assemblies, in addition to creating Assets/P4Connect/Editor/x86/p4bridge.dll  

2. In Visual Studio, check your build configuration, making sure that the settings for p4bridge are "x86_64" and that the p4bridge project is selected.
   Then build all.  In addition to rebuilding all the .NET assemblies,  This will create Assets/P4Connect/Editor/x86_64/p4bridge.dll 

3. In OSX Build both versions (32 and 64 bit) of the p4bridge using 

    - xcodebuild -target p4bridge -configuration Release32
    - xcodebuild -target p4bridge -configuration Release64 

    You will now have `Assets/P4Connect/Editor/x86/p4bridge.dylib` and `Assets/P4Connect/Editor/x86_64/p4bridge.dylib`

## Packaging P4Connect

1.  Copy the OSX assets to the Windows machine where you built the .NET Assemblies,  put them in the right location in the Asset Tree of the project
    you pointed at with your AssetTarget.txt files.

2.  In Unity 4 (Not 5, or you will not be able to use what you build in Unity 4),  Verify that everything works, and that your OSX assets are in the right 
    location.

3.  Open the "Project" pane, and select "P4Connect".

4.  Assets-> Export Package...

5.  Uncheck "Include Dependencies",  Also uncheck anything not under "p4Connect" and uncheck "Config.Asset" if it exists.  

6.  Click "Export", and select a name for your new p4connect.unitypackage, then "Save".

## Installing P4Connect

In Unity, go to Assets -> "Import Package" and then select the unitypackage you created.

## Suggestions? Questions?

Please send all questions / suggestions / criticisms to support@perforce.com