README.txt #1

Perforce P4Simulink Source Distribution

==========================================================================

Directory Structure:

P4Simulink
|- build                    Files generated during build
|- examples                 Sample code and Javadoc for Simulink SCM API
|- libs                     Simulink SCM API jar files                     
|- p4-bin                   p4d binaries used during tests
|- src
|  |- test                  Source code for functional tests
|  |- main                  Source code for the P4Simulink integration

==========================================================================

Building P4Simulink:

Prerequisites:
==============

You must have the following installed on the system on which you want to
build the integration:

  * JDK 1.7+
  * Gradle 2.0+

Note that gradle will download all required external dependencies as part
of the build process.

Tests
=====

Running the functional tests can be done via gradle:

1) gradle clean && gradle test

The included tests start up a p4d instance, restore some data from checkpoint
and then run the P4Simulink functional tests against this instance. It runs
on localhost:1999.

Building
========

Building the jar is done via the 'build' gradle target. Note that the process
builds a "fat" jar in that all dependent jars are included in the end result.

1) gradle clean && gradle build

The target jar will appear in build/libs/ and should follow the pattern:

P4Simulink-BRANCH-VERSION.jar where BRANCH is "dev" (development) or "main"
(production) and VERSION is the version number (based on changelist ID).

Installation
==========================================================================

Installing the SCM plugin in Simulink requires editing the classpath.txt
file. You will need to know the absolute path to the P4Simulink jar file.

1) Start Matlab
2) In the command window enter (without quotes): "edit classpath.txt"
3) Scroll to the bottom, and add the absolute path to your P4Simulink file
4) Save the file, and restart Matlab
5) Check that P4Simulink is loaded by going to:
      New > Simulink Project > From Source Control
   and looking for Perforce as one of the options in the drop-down

Connecting to Perforce
==========================================================================

P4Simulink uses a .p4config file in a project's root directory ("sandbox"
in Simulink) to store the user name, port, and workspace (client) names.
If a .p4config file exists in the project's root directory, it is loaded.
If not, or if the .p4config file is missing one of the fields, you will
be prompted for the missing fields and a .p4config file will be written.

Sample .p4config file:

P4USER=username
P4PORT=perforceserver:1666
P4CLIENT=workspacename

These three values are enough for P4Simulink to attempt to connect to the
Perforce server. Once connected, a password will be requested should one be
required. If the specified workspace does not exist, P4Simulink will
attempt to create it by prompting you for a depot path. The client's root
will be set to the sandbox root given in the Simulink project creation
window, and a default view will be created, where DEPOT_PATH is the path
entered at the prompt, and CLIENT_NAME is the specified workspace name:

DEPOT_PATH //CLIENT_NAME/...

Notes:
==========================================================================

1) Clicking "Add to Project" will add the specified file(s) to the
Simulink project, and open the file for add locally. The file(s) will show
up under "Modified Files" and you must commit (submit) the file in order
to complete the process.

2) Clicking "Get File Lock" will open the specified file(s) for edit
within Perforce. The file(s) will show up under "Modified Files" and you
must commit (submit) the file in order to complete the process.

3) Editing a file without clicking "Get File Lock" will do nothing
unless the file is saved. Once the file has been saved and the Overwrite
button is clicked (because Perforce keeps local files as read-only by
default) the file will be opened for edit.

4) Clicking "Get File Lock" will first retrieve the latest version of the
file before opening it for edit.

5) "Remove from Project" will commit the remove action, but will *not*
delete the local file.

6) Compare against another revision will use the "p4 print" command to
stream the non-head revision to the user's machine. Local files are not
updated.