# 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 `//public_depot/guest/perforce_software/p4connect` into 
a personal development branch.   I used `//public_depot/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 seperators.

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

## 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-enableing 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.

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

In the C++ Bridge code, you can add debug statements using the LOG_XXX statements defined in P4BridgeServer.h

The output from these statements will be passed back out into managed code, and then written to the p4log file,
if specified in your configuration settings.

To print debug information you can of course, use `Debug.Log("message")`, but this dumps an entire stack trace in addition to your message,  for a tidyer output,
consider using "p4log" or "p4logarray" calls (defined in P4Connect.Main.cs) to send individual lines to the p4log file.

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

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