ScribesTools¶

Features¶

GanttProject allows to create milestones and hierarchies of tasks related with dependency constraints. Different fields can be attached to milestones and tasks. This includes for instance “priority”, “cost”, “start date”, “duration”, etc. Custom fields can also be added.

gantt diagram editor - the house building example

GanttProject is mostly an editor for gantt models (see above). It also contains a viewer for pert models (see below). These read-only views are generated automatically.

pert diagram viewer - the house building example

GanttProject also supports resource allocation models. Resources can be attached to tasks.The tool generates a resource allocation model showing the allocation of each resource along the project (see below).

resource allocation viewer - house building example

Interoperability¶

Microsoft Project and CSV files can be imported and exported from the Graphical User Interface (GUI). GanttProject can also generate PDF, PNG, JPEG.

The tool use an .xml format reasonably simple so interoperability with other tools is also possible with some development.

The tool also has (a quite limited) Command Line Interface (CLI) allowing to export models in different formats.

Installation¶

• Download the archive web
• Copy the archive into %SCRIBESTOOLS% and extract it here.
• Rename the directory to obtain %SCRIBESTOOLS%\GanttProject.
• Copy the gandttproject.cmd into the directory.
• Add %SCRIBESTOOLS%\GanttProject to the PATH variable

Launching GanttProject¶

GanttProject is mostly used trough its Graphical User Interface (GUI), but it also has a Command Line Interface (CLI) allowing some limited kind of automation. In a (new) shell you can type the following command to see the help about the CLI:

ganttproject.bat -h

The normal way to use the program is the GUI tough. You can launch it just clicking on the executable or the shortcut that the installer might have created.

When launched, one way to see what GanttProject is all about is to load house building example. In order to do that use the menu `` Projects >> Open `` and select the HouseBuildingSample.gan file in the installation directory of the tools.

Documentation¶

As far as we know there is no document describing GanttProject. The tool is nevertheless rather easy to use for someone acquainted with project management basics. There is a extended demonstration in the form of a 15’ video (youtube). The house building example is also a valuable resource for learning how to use GanttProject.

You may also want to have a look at the following unofficial documents created by people outside of the project:

• “Apprendre Gantt project Ver 2.6” (local, web) by Lycée du Dauphiné DD & JPG. This tutorial, in french, is rather good.
• “GandttProject Handbook 0.52” (local, web) by alexandre thomas. This handbook is rather obsolete and do not contains too much information.

Example¶

GanttProject is delivered with an example of “house building” project. This project is store in the HouseBuildingSample.gan (local) file in the root of the installation directory.

Graphical User Interface¶

This section describes the main panels of the GanttProject software.

Project¶

Project_NameAndDescription

Project_Calendar

Project_ResourceRoles

Tasks¶

Tasks_Hierarchy

Tasks_General

Tasks_Predecessors

Tasks_Resources

Tasks_CustomColumns

Tasks_CustomFieldsManager

Tasks_GanttGraph

Tasks_PertGraph

Resources¶

Resources_General

Resources_DaysOff

Resources_CustomColumns

Resources_CustomFieldsManager

Resources_TaskList

Resources_TaskAllocation

Tools Interface¶

Gantt projects are saved in .gan files which are indeed xml files. This format can serve as an interoperability mean with other tools and constitutes therefore a potential interface for tools.

The HouseBuildingSample.gan file (local) corresponds to the House Building example. Developing a set of much simpler examples would be useful to serve as test cases and/or specification.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

<?xml version="1.0" encoding="UTF-8"?>
<project name="" company="" webLink="" view-date="2012-12-16" view-index="0" gantt-divider-location="369" resource-divider-location="322" version="2.0" locale="en">
    <description/>
    <view zooming-state="default:6" id="gantt-chart">
        <field id="tpd3" name="Name" width="33" order="0"/>
        <field id="tpd4" name="Begin date" width="33" order="1"/>
        <field id="tpd5" name="End date" width="33" order="2"/>
        <option id="taskLabelUp" value=""/>
        <option id="taskLabelDown" value=""/>
        <option id="taskLabelLeft" value="name"/>
        <option id="taskLabelRight" value=""/>
    </view>
    <view id="resource-table">
        <field id="0" name="Name" width="51" order="0"/>
        <field id="1" name="Default role" width="48" order="1"/>
    </view>
    <!-- -->
    <calendars>
        <day-types>
            <day-type id="0"/>
            <day-type id="1"/>
            <calendar id="1" name="default">
                <default-week sun="1" mon="0" tue="0" wed="0" thu="0" fri="0" sat="1"/>
                <only-show-weekends value="false"/>
                <overriden-day-types/>
                <days/>
            </calendar>
        </day-types>
        <date year="2006" month="2" date="14"/>
    </calendars>
    <tasks empty-milestones="true">
        <taskproperties>
            <taskproperty id="tpd0" name="type" type="default" valuetype="icon"/>
            <taskproperty id="tpd1" name="priority" type="default" valuetype="icon"/>
            <taskproperty id="tpd2" name="info" type="default" valuetype="icon"/>
            <taskproperty id="tpd3" name="name" type="default" valuetype="text"/>
            <taskproperty id="tpd4" name="begindate" type="default" valuetype="date"/>
            <taskproperty id="tpd5" name="enddate" type="default" valuetype="date"/>
            <taskproperty id="tpd6" name="duration" type="default" valuetype="int"/>
            <taskproperty id="tpd7" name="completion" type="default" valuetype="int"/>
            <taskproperty id="tpd8" name="coordinator" type="default" valuetype="text"/>
            <taskproperty id="tpd9" name="predecessorsr" type="default" valuetype="text"/>
        </taskproperties>
        <task id="0" name="Architectural design" color="#99ccff" meeting="false" start="2012-12-24" duration="25" complete="81" expand="true">
            <task id="9" name="Create draft of architecture" color="#99ccff" meeting="false" start="2012-12-24" duration="10" complete="100" expand="true">
                <depend id="10" type="2" difference="0" hardness="Strong"/>
                <depend id="12" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="10" name="Prepare construction documents" color="#99ccff" meeting="false" start="2013-01-07" duration="15" complete="75" expand="true">
                <depend id="17" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="17" name="Agreement on architectural plan " color="#000000" meeting="true" start="2013-01-28" duration="0" complete="0" expand="true">
                <depend id="1" type="2" difference="0" hardness="Strong"/>
            </task>
        </task>
        <task id="11" name="Interior design" color="#99ccff" meeting="false" start="2013-01-07" duration="10" complete="33" expand="true">
            <depend id="6" type="2" difference="0" hardness="Strong"/>
            <task id="12" name="Pre-design" color="#99ccff" meeting="false" start="2013-01-07" duration="5" complete="100" expand="true">
                <depend id="13" type="2" difference="0" hardness="Strong"/>
                <depend id="14" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="13" name="Furniture selection" color="#99ccff" meeting="false" start="2013-01-14" duration="5" complete="0" expand="true"/>
            <task id="14" name="Equipment planning" color="#99ccff" meeting="false" start="2013-01-14" duration="5" complete="0" expand="true">
                <notes><![CDATA[Embedded devices, kitchen, washing machine, dryer etc]]></notes>
            </task>
        </task>
        <task id="7" name="Construction phase" color="#99ccff" meeting="false" start="2013-01-28" duration="75" complete="0" expand="true">
            <depend id="20" type="2" difference="0" hardness="Strong"/>
            <task id="1" name="Foundation building" color="#99ccff" meeting="false" start="2013-01-28" duration="15" complete="0" expand="false">
                <depend id="2" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="2" name="Ground Floor building" color="#99ccff" meeting="false" start="2013-02-18" duration="20" complete="0" expand="false">
                <depend id="4" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="4" name="First Floor building" color="#99ccff" meeting="false" start="2013-03-18" duration="20" complete="0" expand="false">
                <depend id="5" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="5" name="Roof" color="#99ccff" meeting="false" start="2013-04-15" duration="10" complete="0" expand="false">
                <depend id="18" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="16" name="Connect to communications" color="#99ccff" meeting="false" start="2013-04-29" duration="10" complete="0" expand="true"/>
            <task id="18" name="Construction completed " color="#000000" meeting="true" start="2013-04-29" duration="0" complete="0" expand="true">
                <depend id="6" type="2" difference="0" hardness="Strong"/>
                <depend id="16" type="2" difference="0" hardness="Strong"/>
            </task>
        </task>
        <task id="8" name="Decoration phase" color="#99ccff" meeting="false" start="2013-04-29" duration="10" complete="0" expand="true">
            <task id="6" name="Walls" color="#99ccff" meeting="false" start="2013-04-29" duration="5" complete="0" expand="false">
                <depend id="15" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="15" name="Furniture" color="#99ccff" meeting="false" start="2013-05-06" duration="3" complete="0" expand="true">
                <depend id="20" type="2" difference="0" hardness="Strong"/>
            </task>
            <task id="20" name="Bring your family here" color="#000000" meeting="true" start="2013-05-13" duration="0" complete="0" expand="true"/>
        </task>
        <task id="49" name="Survive the End of the World" color="#ff3333" meeting="true" start="2012-12-21" duration="0" complete="0" expand="true">
            <depend id="0" type="2" difference="0" hardness="Rubber"/>
        </task>
    </tasks>
    <resources>
        <resource id="1" name="Jack House" function="Default:1" contacts="jack.house@myselfllc.net" phone="0044 077345456"/>
        <resource id="0" name="John Black" function="4" contacts="john.black@myselfllc.net" phone="+44 0794353567"/>
        <resource id="2" name="Michelangelo" function="0" contacts="mickelangelo@heaven.net" phone="078 9059056"/>
        <resource id="3" name="Tom White" function="1" contacts="tom.white@myselfllc.net" phone="07978978978"/>
        <resource id="4" name="Peter Green" function="1" contacts="peter.green@myselfllc.net" phone="0797897856"/>
        <resource id="5" name="George Brown" function="1" contacts="george.brown@myselfllc.net" phone="07967766447"/>
        <resource id="6" name="John Silver" function="2" contacts="john.silver@myselfllc.net" phone="07778967889"/>
    </resources>
    <allocations>
        <allocation task-id="9" resource-id="1" function="Default:1" responsible="false" load="50.0"/>
        <allocation task-id="12" resource-id="1" function="Default:1" responsible="true" load="100.0"/>
        <allocation task-id="13" resource-id="1" function="Default:1" responsible="true" load="100.0"/>
        <allocation task-id="14" resource-id="1" function="Default:1" responsible="true" load="50.0"/>
        <allocation task-id="15" resource-id="1" function="Default:1" responsible="true" load="100.0"/>
        <allocation task-id="1" resource-id="0" function="4" responsible="false" load="100.0"/>
        <allocation task-id="16" resource-id="0" function="4" responsible="true" load="100.0"/>
        <allocation task-id="9" resource-id="2" function="0" responsible="true" load="100.0"/>
        <allocation task-id="10" resource-id="2" function="0" responsible="true" load="100.0"/>
        <allocation task-id="12" resource-id="2" function="0" responsible="false" load="50.0"/>
        <allocation task-id="14" resource-id="2" function="0" responsible="false" load="50.0"/>
        <allocation task-id="1" resource-id="3" function="1" responsible="false" load="100.0"/>
        <allocation task-id="2" resource-id="3" function="1" responsible="false" load="100.0"/>
        <allocation task-id="4" resource-id="3" function="1" responsible="false" load="100.0"/>
        <allocation task-id="5" resource-id="3" function="5" responsible="false" load="100.0"/>
        <allocation task-id="6" resource-id="3" function="1" responsible="false" load="100.0"/>
        <allocation task-id="15" resource-id="3" function="1" responsible="false" load="100.0"/>
        <allocation task-id="2" resource-id="4" function="1" responsible="false" load="100.0"/>
        <allocation task-id="4" resource-id="4" function="1" responsible="false" load="100.0"/>
        <allocation task-id="16" resource-id="4" function="1" responsible="false" load="100.0"/>
        <allocation task-id="6" resource-id="4" function="1" responsible="false" load="100.0"/>
        <allocation task-id="1" resource-id="5" function="1" responsible="false" load="100.0"/>
        <allocation task-id="2" resource-id="5" function="1" responsible="false" load="100.0"/>
        <allocation task-id="4" resource-id="5" function="1" responsible="false" load="100.0"/>
        <allocation task-id="6" resource-id="5" function="1" responsible="false" load="100.0"/>
        <allocation task-id="1" resource-id="6" function="2" responsible="true" load="100.0"/>
        <allocation task-id="2" resource-id="6" function="2" responsible="true" load="100.0"/>
        <allocation task-id="4" resource-id="6" function="2" responsible="true" load="100.0"/>
        <allocation task-id="5" resource-id="6" function="2" responsible="true" load="100.0"/>
        <allocation task-id="6" resource-id="6" function="2" responsible="true" load="100.0"/>
    </allocations>
    <vacations>
        <vacation start="2009-02-02" end="2009-02-09" resourceid="1"/>
    </vacations>
    <taskdisplaycolumns>
        <displaycolumn property-id="tpd2" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd7" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd8" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd6" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd10" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd11" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd9" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd1" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd0" order="-1" width="75" visible="false"/>
        <displaycolumn property-id="tpd3" order="0" width="122" visible="true"/>
        <displaycolumn property-id="tpd4" order="1" width="122" visible="true"/>
        <displaycolumn property-id="tpd5" order="2" width="121" visible="true"/>
    </taskdisplaycolumns>
    <previous/>
    <roles roleset-name="Default"/>
    <roles>
        <role id="0" name="Architect"/>
        <role id="1" name="Bricklayer"/>
        <role id="2" name="Foreman"/>
        <role id="3" name="Decorator"/>
        <role id="4" name="Excavator operator"/>
        <role id="5" name="Roofer"/>
    </roles>
</project>

Features¶

Modelio if a full-fledged modeling environment supporting:

• model edition and validation for a wide range of modeling languages,
• model distribution over the web,
• model versioning with SVN (commercial edition only),
• documentation generation,
• code generation and or reverse engineering of C++, Java, C#, Hibernate, SQL, XSD...

Modelio can be extended to add more features via java modules or python scripts.

Installation¶

Modelio exists both in an open source and commercial version. You need a licence in the later case.

Launching Modelio¶

If a shortcut has been created to launch Modelio (it depends on your platform), you just have to click on it. Otherwise you can click on the executable (modelio or modelioexe) in the installation directory.

Modelio can be launched within a script or from a shell with a command line like that (here the installation directory is %SCRIBESTOOLS%\ModelioOpen\):

%SCRIBESTOOLS%\ModelioOpen\modelio.exe    # modelio on unix

It could be wise to create a command to add parameters (or to change the shortcut on windows) in order to display the console window and run the Modelio in debug mode (this allows to have more messages in the console in case of modelio errors):

%SCRIBESTOOLS%\ModelioOpen\modelio.exe -mdebug -consoleLog

If you get an error ‘exit code 13’ it is likely that the java and modelio architecture (32 bits or 64 bits) do not match.

Note that on the first launch Modelio could take quite some time (up to a few minutes) to start. This could be the case on a slow computer or if your home directory is on a remote server. Modelio creates the ‘module catalog’ and this involves big files. After this, Modelio shows a “Welcome” page. You can simply close it.

Documentation¶

Documentation on Modelio is available from the Help > Help menu of Modelio as shown below. You will most probably want to use the section Modelio Modeler if you are just interested in using modelio.

Different kind of documentation is also available on the web:

• user documentation
• developer documentation (for developing extensions)
• FAQ
• a few tutorials (including some videos)

Working with Projects¶

Just like in many software engineering environments Modelio is based on the notion of “Workspace” (a directory) which contains “Projects” (subdirectories inside the workspace directory).

Scripting with Modelio¶

This section shows how to extend Modelio with its scripting feature. Jython is the scripting language. Jython is just Python running on a Java virtual machine. Otherwise this is the same programming language. Simply put Jython programs can call all python libraries but also all java libraries... Modelio is writen in java but Jython makes it possible to use its full API and this without the burden to compile, package, deploy java plugins.

The first sub section shows how to use Jython interactively in the console. The next section shows how to store scripts in .py files to ease development and use regular text editors or python environments.

<?xml version="1.0" ?>
<catalog>
    <script name="HelloWorld" path="helloworld.py" icon-path="" show-menu="true" show-toolbar="true">
        <description></description>
    </script>
</catalog>

print 'hello world!'

Modelio metamodel¶

The Modelio API is based on Modelio metamodel. This metamodel integrates in a single metamodel 3 languages:

• UML the Unified Modeling language, an international standard.
• BPMN the Business Process Modeling Notation, an international standard.
• “Analyst” a modelio proprietary language for requirements engineering.

The metamodel is made of about 300 metaclasses spread in about 30 packages.

Modelio metamodel is proprietary. Although is neither compatible with the standard UML metamodel nor the standard BPMN metamodel but it support most of the features of these languages (in an integrated way).

The are three ways to explore Modelio metamodel:

• browsing the “metamodel documentation”.
• browsing the “API javadoc”.
• using the “CoExplorer”.

Metamodel documentation¶

The metamodel is described in the modelio metamodel documentation. Each metaclass is described in an web page containing a class diagram centered around the metaclass. See for instance the page for the “class” metaclass.

Documentation of the “class” metaclass

Note that the images are clickable. The best way to find a metaclass in this documentation is probably to use the metamodel index (and using the “search” feature of the browser).

API javadoc¶

Using the modelio API javadoc is another alternative. There are more than 500 classes and 67 packages in this API,but this is because the API provides many other services. The metamodel is just about “model mangagement”. In other words, all metaclasses are in the javadoc but there are more classes.

Have a look to the “class” metaclass javadoc and compare it the corresponding “UML” documentation. As you can see the content is the same although the javadoc page just reflects that the API is implementated in java. Naming conventions allows to go from the API to the metamodel seamlessly.

Javadoc of the “class” metaclass

CoExplorer¶

Another alternative, most probably the most convenient one, is to use the CoExplorer plugin. This plugin (actually a jython macro) should be installed in order to be used. Once installed select the elements to be explored in modelio and then press the CoExplorer button in the top right toolbar.

A session with the CoExplorer plugin.

The CoExplorer allows to explore at the same time a model and the metamodel.

TODO

to be documented

Collaborative Modeling with SVN¶

Thanks to the TeamworkManager module Modelio can store projet fragments in a remote SVN repository. TeamworkManager allows various users to work on the same model at the same time.

The documentation to create and use SVN fragments with TeamworkManager is available in the menu help of Modelio (but not on the web). It can be found in the section Modelio by Modeliosoft extensions > Teamwork as shown in the figure below.

Connecting to a SVN repository¶

Open the project in which you want to add the access to SVN. A project is a set of fragments; there is always one local fragment, the one where you work. In this section a remote fragment will be added, the one that correspond to the SVN repository.

Work models are the fragments in read/write mode. That is, the fragment where the developer work. To add the possibility to work on the SVN model select the menu Configuration > Work Models.

In order to register the SVN repository as a remote work model, click the Add button in the SVN models section of the following window:

In the following form, you can choose a name for the fragment itself. The URI of the svn repository must be provided as well as the credentials for accessing it (if required). Checking the URI with the corresponding button is a good idea.

A new remote fragment is then available in your project as shown in the window below.

You should be able to use it and modifying it. The version control commands to use are mostly:

• update: to get the last updates from the central SVN repository,
• commit: to commit the local changes to the central SVN repository/

Installation¶

Installing USE is rather easy:

• download the use zip file (web).

• extract this zip file where you want to install it (e.g. %SCRIBESTOOLS% on windows).

• rename the newly created directory to %SCRIBESTOOLS%\UseOCL.

• for convenience add the bin directory to your system PATH. For instance the PATH could look like:

  %SCRIBESTOOLS%\UseOCL\bin; ...   # Windows. ; is the separator
  /home/pablo/UseOCL/bin: ...     # Unix.    : is the separator
  

Launching USE OCL¶

Once installed, you can just type the following command in a new shell:

use -nogui

If the bin directory is not in the PATH, then you have type the full path to use binary). This launch the USE OCL Command Line Interface (CLI).

A session with the Command Line Interface. Use is started and then some OCL expression are evaluated with the ? command.

If you want you can also have a look at the graphical interface (in this case just type:

use

The Graphical User Interface.

Documentation¶

There is quite some documentation for USE OCL. We recommend the following order:

0. Two “cheat sheets” are provided in one file (local):

   • On one page, the OCL language is described according to the standard.

     

   • On the other page, the languages of the USE environment are described: (1) the specification language (.use) which includes OCL, but also (2) the action language (.soil).

     

1. The “cheat sheets” just describe the language. To understand how USE can be used read first the quick tour (local, web). A MUST READ. A simple class model with 3 classes, 3 associations and 4 OCL invariants.

2. Watch then the video (local, web). The first part (until frame 128/208) deals with the static part and invariants. The second part deals with dynamics, operation simulation and pre/post conditions. You may be interested only by the first part or by both parts.

   

3. If necessary use the reference documentation (local, web). Use this document as a reference, for instance to check something about USE OCL language. Note that chapter 6 (page 82) contains the list of OCL operations supported by OCL USE.

   Note

   This documentation has not evolved for quite some time. More features have been added to USE OCL, in particular to follow the evolution of OCL/UML or to remove some limitations. For instance support for qualified associations is possible although undocumented. Use the cheat sheet for updated information. If needed the directory examples and/or test of the distribution contains also some examples demonstrating the use of these features. For instance various qualified association examples are visible in the test/t086.use.

use -nogui

Syntax¶

The syntax of OCL and USE/SOIL languages is summarized in (local). Only particular points are exemplified below.

enum Season {winter, autumn, spring, summer}

Season::winter

Classes¶

Classes can be defined as following:

class Yellow
end

abstract class Something
end

abstract class Fruit < Something
end

class Banana < Fruit, Yellow
end

UML:

class Banana
attributes
    length : Integer /* Integer, Real, Boolean, String */
    growthTime : Season
    -- Tuple, Bag, Set, OrderedSet, Sequence
    goodies : OrderedSet(Bag(Sequence(Set(Tuple(x:Integer,y:Real,z:String)))))

    remainingDays : Integer
        init: 42                           -- attribute initialization
        derived: self.length * self.size   -- attribute derivation

end

class Banana
operations

    sleep()                        -- operation signature

    wakeUp(n : Integer):String     -- operation specification
        pre notTooMuch: n > 10 and n < self.length     -- precondition
        post resultOK: result > 'anaconda'             -- pôstcondition

    helloJungle() : String         -- operation implementation (SOIL)
        begin
            declare x : Banana ;
            WriteLine('hello') ;
            x := new Banana ;
            self.length := self.length + self.remainingDays*20+3 ;
            result := 'jungle' ;
            destroy x ;
        end
        pre freshEnough: self.remainingDays > 10

    smash() : Integer               -- operation/query (OCL)
        = self.length + Set{4,2}->size*42
end

Associations¶

UML:

USE:

association Owns between
    Person [1] role owner
    Car[*] role ownedCars
                            -- more roles for n-ary association
end

An example of link:

SOIL:

! insert(tian,c232) into Owns

Association Classes¶

UML:

USE:

associationclass Hate between
    Monkey [*] role monkeys
    Snake [*] role snakes
attributes
    reason : String
    intensity : Integer
operations
    increase()
end

SOIL:

! c := new Hate between (chita,kaa)
! c.reason := "kaa is really mean"
! c.intensity = 1000

Qualified Associations¶

Let us consider this following qualified association.

Note the qualifier construct in the USE association definition:

association APourDirigeant between
    Association1901[*] role associationsDirigees  qualifier(titre:String)
    Person [0..1] role dirigeant
end

The example below represents a valid object model.

Note the insert(<role>{<value>...} SOIL construct to create new link and .<role>[<value>] to traverse links:

! insert(petanque38{'president'},antonio) into APourDirigeant
! insert(petanque38{'secretaire'},antonio) into APourDirigeant
! insert(petanque38{'tresorier'},djamila) into APourDirigeant
? petanque38.dirigeant['president']
? petanque38.dirigeant

Creating diagrams¶

USE Graphical User Interface (GUI) can be used to create class diagrams as well as object diagrams (among other kind of diagrams).

In order to do so launch use without the -nogui option. If you want to get both a class diagram and a object diagram specify both a .use and .soil file on the command line. Something like:

use -nr CyberGarage.use scenarios/CyberGarage/scenario.use

To create a diagram then use the menus:

• View > Create View > Class Diagram and
• View > Create View > Object Diagram

Many useful options are then available in the contextual menu of each diagram (right click).

Many options are available. You are likely to use:

• Auto-Layout to get a first layout automatically. Don’t apply this option on an existing layout ...
• Save-Layout to save the layout after some manual arrangement. This save the diagram layout in the form of a .clt (Class LayouT) file or .olt (Object Layout) file depending on the diagram. Quiting use without saving the current layount will create the file ‘...-default.clt’. It is a bad practice to use this file, especially when various diagrams are to be build. Save the layout in proper files with proper names.
• Show muliplicities, Show role names, etc.

If you intend to create various diagrams for the same model (to create different views) you are likely to use Hide options.

v803 := new Vehicule('v803')

Using PyCharm IDE¶

USE specifications are just plain text files. A regular file editor and a shell are just enough to work with USE.

You may however want to use syntax highlighting with PyCharm (see PyCharm for installation instructions). Read also Launching PyCharm. When you launch PyCharm select the “project directory”, the top directory that contains all your files including the .git subdirectory if you use git.

PyCharm has to be configured and this imply to follow various steps. A PyCharm plugin has to be installed and a few configurations files have to be copied. At the end you will get the following result.

Using PyCharm for USE syntax and output highlighting

The figure shows the following elements:

• On the left a .use specification is “syntax-highlighted”. This is handy especially if the OCL language is used as they are many keywords and operations.
• On the right a .soil scenario is “syntax-highlighted”. This is handy since there is typically a lot of comments in such a scenario; the statments are much more visible in this way.
• On the top bar, a button allows to check the scenario against the specification. There is no magic here, this button should be configured.
• On the bottom window, the output of USE is displayed with colors for errors. This is quite handy when the output is large.

The instructions below will allow you to get an environment as shown in the following picture. If you are just going to se USE OCL only once don’t waste your time. Use a regular editor. Otherwise your might consider following the procedure below.

Output highlighting¶

To get the output of USE OCL colored (to see the errors as shown in the figure above) three steps should be followed:

1. Installing the Grep Console plugin
2. Installing a configuration suitable for USE OCL
3. Creating a “Run Configuration”

Installing Grep Console¶

In PyCharm go to File (menu) > Settings (menu) > Plugins (tab) > Browse Repositories (button).

Note

If you computer is behind a firewall you have to specify a proxy. In this case select HTTP Proxy Settings > Manual Proxy Configuration and fill the parameters. For instance at the UGA you will need to enter: HostName : www-cache.ujf-grenoble.fr, Port Number : 3128

A list of plugins should be displayed. Type "Grep" in the search field and install Grep Console.

Configuring Grep Console¶

The Grep Console plugin allows to associate colors to regular expressions matching program outputs. Download the (GrepConsole.xml) file which defines a configuration suitable for USE outputs. PyCharm should be stoped. Copy this file into the .PyCharm50/config/options directory (see above). Override the existing file with the same name.

Creating a Run Configuration¶

Environments like PyCharm use Run Configuration to launch repetitive tasks. PyCharm should be stopped. Copy the (checkScn001Razamanaz.xml) configuration in the directory .idea/runConfigurations of your project (create the directory runConfigurations if it does not exist already). After starting PyCharm and selecting the menu Run > Edit the Configuration you should see the following configuration:

The checkScn001Razamanaz configuration parameters

Adjust this configuration where necessary.

At the time of writing this configuration refers to the ScribesInfra repository which must be clone at the same level.

Note

As an alternative to PyCharm, on Windows, you can use notepad++. A syntax file is available for OCL sources although it is not updated, do not support .soil files nor output highlighting.

To install this file:

• in Notepad++ go to “Main menu > Language > Define your language... > Import ...“
• select the file USE_Notepad_plusplus_User_Defined_Language.xml web.
• You may have to restart notepad++.

Examples¶

Various examples of use specifications are available in the distribution web in particular in the directory examples.

The file README.examples (local) provides an interesting index that show which OCL features are used in which files.

Features¶

KMADe is an editor of task models.

task model by Sybille Caffiau

Interoperability¶

KMADe represents task models as kxml files.

Installation¶

KMADe is easy to install:

• Download the KMADe zip archive web.
• Move this file to the directory %SCRIBESTOOLS%`.
• Unzip the file here.
• Rename the created directory to KMADe
• Remove the zip file if you want.

Launching KMADe¶

Once installed, you can just have to double click on the kmade.jar file in the installation direction. KMADe should start as this is a java executable.

Documentation¶

KMADe has an extensive documentation (local, web) but it is mostly in french.

Installation¶

See the installation page for detailed information. Install the application in a directory like %SCRIBESTOOLS%\Pandoc.

On Windows:

• download pandoc-1.15-windows.msi web.

• if you are on a personal PC just click on the executable. If the application should be installed on multiple users type instead:

  msiexec /i C:\DOWNLOADS\pandoc-1.15-windows.msi ALLUSERS=1 APPLICATIONFOLDER=%SCRIBESTOOLS%\Pandoc
  

On Ubuntu:

sudo apt-get install pandoc

Launching Pandoc¶

To test your installation type in a new shell:

pandoc --version

Documentation¶

There is a lot of documentation online. The user guide describes command lines options. .. ............................................................................

Features¶

SchemaSpy reads a relational database and

• generates a XML file corresponding to the database schema
• detects a few kind of defaults in the database design

Examples of defaults detected by SchemaSpy

• generates a html site a la javadoc with clickable entity-relationship diagrams.

Example of diagram generated by SchemaSpy

Interoperability¶

SchemaSpy is particularly interesting because the reverse engineering process generates a rather simple XML file so that other tools can be build by consuming this file.

Installation¶

To install SchemaSpy:

• Download the SchemaSpy jar file web.
• Create the directory %SCRIBESTOOLS%\SchemaSpy.
• Move the schemaspy-6.0.0-rc1.jar file into %SCRIBESTOOLS%\SchemaSpy\schemaSpy.jar.
• Add %SCRIBESTOOLS%\SchemaSpy to the system PATH.
• Copy the files schemaspy.bat and schemaspy.sh into the directory

Launching SchemaSpy¶

You can check if the installation (in a new shell) by trying the -dbhelp option:

schemaspy -dbhelp

This command should display a rather long list of supported database types, with the option to use to connect to the database in each case.

You need an access to a SQL database if you want to execute SchemaSpy. The command line options are described in the documentation.

Documentation¶

The documentation is available on the web. It mostly describes the many possible command line options of SchemaSpy. There is also an example of generated html, “library example”.

SchemaSpy and SQLite¶

The SQLite driver delivered with SchemaSpy is not working. If you want to use SQLite, a driver and a property file must be installed:

• make sure that the driver have been installed (see the Installation section of SQLite). This results in the driver %SCRIBESTOOLS%\SQLite\sqlite-jdbc.jar.
• Copy the file sqlite.properties into the directory %SCRIBESTOOLS%\SchemaSpy.
• Adjust the location of the driver in the sqlite.properties file.

To use a SQLite database file you will have to specify the path to the property files with the -t option: For instance the following command line generate the documentation of the database db.sqlite3 in the docs\SchemaSpy directory:

schemaspy -t %SCRIBESTOOLS%/SchemaSpy/sqlite.properties -db db.sqlite3 -sso -o docs\SchemaSpy

With oracle:

schemaspy -t orathin -host im2ag-oracle.e.ujf-grenoble.fr -port 1521 -db ufrima -s MYLOGIN -u mylogin -p * -o out

Features¶

The tool provides:

• extracted information about database schemas in various formats (e.g. text, json, csv, html5)
• documentation generation with ER diagrams generated by graphviz,
• lint like quality insurance,
• grep/diff like support.

The API allows to access to SQL databases in an homogeneous way.

Installation¶

To install SchemaCrawler:

• Create a directory that will contain the software (e.g. %SCRIBESTOOLS%\SchemaCrawler).
• Download schemacrawler-12.06.03-main.zip web.
• Extract the content of the archive in the target directory.
• As a result you will 3 sub directories _ivy, _schemacrawler, examples.
• Add the directory to the system PATH

The sc scripts provided (“sc” stands for SchemaCrawler) assume that this command will run in the _schemacrawler directory. In order to remove this constraints replaces the content of _schemacrawler\sc.cmd by:

@SET DIR=%~dp0
@java -classpath %DIR%/lib/*;%SC% schemacrawler.Main %*

On unix replace the content of _schemacrawler\sc.sh by:

#!/bin/sh
SC=`dirname $0`
java -cp $(echo $SC/lib/*.jar | tr ' ' ':') schemacrawler.Main $*

SchemaCrawler is written in java but supports scripting with different languages (). In order to use Python for Scripting the following commands should be executed (assuming that the directory is %SCRIBESTOOLS%\SchemaCrawler):

cd %SCRIBESTOOLS%\SchemaCrawler\_ivy
download.cmd python     # use download.sh on unix

Launching SchemaCrawler¶

The simplest test to installation is to type the following:

cd %SCRIBESTOOLS%\SchemaCrawler\_schemacrawler    #  to be adapted if necessary
schemacrawler --version
schemacrawler --help

This should display the version of SchemaCrawler and then the help of the command line.

To go further the directory examples contains many examples of usage. A HSQLDB database server is provided for testing purposes. To launch this example database server open a shell window and type the following commands:

cd %SCRIBESTOOLS%\SchemaCrawler\examples     # directory to be adapted if necessary
StartDatabase.cmd                           # .sh on unix

At that level the test server should be running in this window (and the window color may have changed).

Open another shell and try:

cd %SCRIBESTOOLS%\SchemaCrawler\_schemacrawler     # to be adapted
sc.cmd -server=hsqldb -database=schemacrawler -password= -infolevel=detail -command=schema

schemacrawler -server=hsqldb -database=schemacrawler -password= -infolevel=detail -command=schema

If you have a sqlite database you can also try:

schemacrawler -server sqlite -database <path to the sqlite file>\db.sqlite3 -infolevel=maximum -password=  -command schema

Documentation¶

The documentation of the command line interface is available via the command:

schemacrawler -help

The detail of the API is documented through SchemaCrawler javadocs.

Examples¶

The directory examples of the installation contains examples of use for the command line interface, for scripting or for the API.

Features¶

Checkstyle comes by default with configurations files supporting Sun Code Conventions and Google Java Style but nearly everything can be configured. New checks can be written in java classes so nearly all kind of coding standards can virtually be implemented with Checkstyle.

Interoperability¶

Checkstyle is already integrated in many different IDE in the form of plugins for instance. There is a large list of tools related to Checkstyle.

Installation¶

On Ubuntu you can install CheckStyle has following:

sudo apt-get install checkstyle

Installing CheckStyle as a standalone tool is easy:

• Create a directory %SCRIBESTOOLS%\CheckStyle.
• Download checkstyle-X.Y-all.jar web.
• Copy the jar file into %SCRIBESTOOLS%\CheckStyle\checkstyle-all.jar (remove the version number).
• Copy the files checkstyle.cmd and checkstyle.sh into the directory.
• Add the %SCRIBESTOOLS%\CheckStyle directory to the path.

Launching CheckStyle¶

You check the installation as following. The option -h and -v display the CheckStyle help and version respectively:

checkstyle -h
checkstyle -v

If you have a java program at hand (let’s say MyProg.java) and you want to use Sun Code Conventions on it type:

checkstyle -c /sun_checks.xml MyProg.java

Documentation¶

A lot of documentation is available online web.

Installation¶

Installation instructions (web) depends on the platform used but basically PyLint is installed via python pip or platform specific package installers (e.g. apt-get on debian or ubuntu). With pip just type:

pip install pylint

On Unbuntu you can install pylint as following:

sudo apt-get install pylint

Lauching PyLint¶

To try the installation type:

pylint --version
pylint --help

Documentation¶

The documentation is available on http://docs.pylint.org/

Features¶

Diigo allows to:

• manage bookmarks (and store them in the cloud, not on your computers)
• create notes and create libraries of images from the web
• annotate any web pages and also pdf from the web
• create groups and share information (bookmarks, notes, annotations) among these groups
• generate rss feeds that are updated every time you publish a new link

Installation¶

You have fist to register to Diigo and select the free plan. This will give you access to the web interface of Diigo.

Diigo web interface for managing groups

To take the full profit of Diigo (and in particular to add annotations) you should install a plugin for you favorite browser. You can either search the web for with google diigo plugin chrome for instance or use the Diigo tools page (use the Extension/Web Apps). Diigo is also available on android and iphone.

“Annotate & Capture the Web” in action, the plugin for Chrome

Creating an account¶

To get a free account use ‘Pricing’ and then click on the link Sign Up for a Free Plan that is on the page as shown below:

You can sign up with a google account. Otherwise you will just need to a few information: username, password, email, first name, last name.

Select add a SVN repository if this is what you want and give it a name. That’s all.

Adding collaborators to a repository¶

To add collaborators to the repository click on the repository and then select the Team tab. You just have to enter the email of each collaborator and select their status for the selected repository:

• member for read/write access
• watcher for read access

Using a SVN repository¶

SVN repositories are used remotely via SVN client. In order to do this you must know the URI of the repository and give this URI to the client. The URI can be found on the repository page in the SVN tab in the Checkout URL field as shown below.

Overview¶

It is important to clearly distinguish right from the beginning Git and GitHub. Git is a general tool for versioning like SVN. GitHub is a hosting service based on Git and also a particular tool (the GitHub client) that can be installed on your machine.

Git¶

Git is a toolkit that can be used in a totally standalone mode, that is locally on any kind of machine (e.g. a laptop running windows/linux/mac). This is essentially a set of commands that you can run in a shell.

A shell with a typical git command git status

Git can be used both locally by a single developer but also locally and on the web in a collaborative mode.

• git for local usage.

  One interesting aspect of Git is that it is file-based repository: installing it do not necessitate to install any kind of server, database; no daemon process is required, etc. Using git locally is therefore cheap and easy. It will just create a .git directory in your project directory and that’s all. Full stop. Git can be useful really useful when working alone. This provides you some revision control for instance.

• git for collaborative usage.

  Obviously if the goal is to collaborate with others one need a git server. In this case the local copy of Git installed on your machine will serve as a client. You can setup a git server (if you are in a company) or reuse existing services from the cloud.

The next section is about git on the cloud.

GitHub or/and BitBucket¶

If you need to collaborate with others to develop an open source project, GitHub or BitBucket are obvious solutions to consider, at least if you plan to use Git. They both provide hosting public git repositories for free. GitHub and BitBucket have web-based interfaces to explore repositories.

A git repository as shown on github

A git repository as shown on BitBucket

We highly recommend to use GitHub, unless if you need private repository. If you want you can have a look at the article bitbucket vs. github or to have a look at a more general comparison of hosting services.

Here we will use GitHub since:

• this is the most popular service,
• it provides an excellent git client which is amazingly easy to use.

If you need to have a private repository, and want to have that for free, then you have to use BitBucket for that repository. By contrast to Github (which offer only public repository), BitBucket provide unlimited private repositories (will a limit of 5 collaborators including you). The good news is that tools work with any provider so the solution is most probably: all public repositories on GitHub, all private repositories on BitBucket.

Installation¶

In this section you will learn how to:

1. create a github account.
2. install the github client for your machine.
3. install a true ‘git’ toolkit (only if you need it).

Creating a GitHub account¶

Extremely simple. Just go to https://github.com/join and fill the various fields. In step 2 select a free plan. Basically this is it.

Joining GitHub - step 1

Installing the BitBucket client¶

The github client is really easy to use. However if you want to learn more about git and want to do some advanced things without the shell, the github client is not the best choice. In fact, it hides some commands behind some cool features like ‘Sync’. You might prefer another client, for instance the one proposed on BitBucket. This git client is called SourceTree.

SourceTree at work

Your can download it from the SourceTree home page. It works on windows and mac.

Using the git shell¶

The github client installed in the previous sessions include not only a graphical interface, but also give you access to a git shell where you can type all commands.

Launching a git shell from the Windows GitHub client

While the GUI is very nice and enough for most situations, sometimes you will need to type git commands that are not available in the GUI. In this case using the git shell is the solution.

Installing the git toolkit¶

In some situations you will however have to install a git toolkit.

Git web site.

You have to install git:

• if you have not installed the GitHub client at all (either because you do not want or because it is not available on your platform).
• if you want to run some scripts with git commands but you cannot always run them from the GitHub shell (e.g. launching them from a cron tab).
• if you use some programs relying on the availability of git commands (those program will complain that git commands and not available).

In these case you will have to install git (possibly in addition to github client). In order to do so, just download git and install it following the instructions for your platform (e.g. for windows web).

On Ubuntu you can install git as following (if it is not already installed):

sudo add-apt-repository ppa:git-core/ppa -y     # if you want the last version
sudo apt-get update                             # if you want the last version
sudo apt-get install git
git --version

Configuration¶

If you use the command line, you should configure git. The option --global save the configuration in your .gitconfig home file. Otherwise you could configure this for individual project.

Configure who you are (changing escribis by your github account):

git config --global user.name "escribis"
git config --global user.email "escribis@users.noreply.github.com"

To avoid typing always your password (see Caching you Github password):

git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

You may also configure (Dealing with line endings):

git config --global core.autocrlf input    # if you use unix

Overview¶

Let us consider as an example the aeis course of the m2r school. with a typical scenario implying the a group G12 in which two students working in pair:

• Noe and
• Babako.

Obviously these values has to be replaced by actual values in the commands presented later.

All information about the course aeis is available on github.com. Each group can see three repositories:

All repositories lives on GitHub. For instance babako and noe have at their disposal a “group repository”, at https://github.com/m2r/m2r-aeis-G12. This repository is private so only Noe, Babako and teachers can see it when logged in on GitHub.

This repository will be shared by Noe and Babako to work together. It will contain the final result evaluated at the end of assignments. In practice Noe and Babako will clone this repository on their local machines, will work separately on their local repositories and “push” and “pull” modification to the “group repository”. When the deadline will arrive the content of the “group repository” m2r-aeis-G12 will be evaluated.

Scenario¶

The steps below provides an overview of a possible process. Technical details are provided in the next sections.

1. Noe installs the git toolkit on her machine or uses git it at the university.
2. Noe first configures git on the local account(s) she uses (on her machine, at the university, or both).
3. Noe is at the university. She “clones” locally the “group repository” from GitHub in a home directory.
4. Noe “pulls” the assignment skeletons from the m2r-aeis-root repository. She gets the different files on her account at the university.
5. Noe puts Babako and her name in the CONTRIBUTORS.md file. She “commits” and “pushes” this changes to the “group repository” on GitHub.
6. Noe browses the assignments, looks at existing WorkItems, makes some first changes in order to start implementing the first assignment.
7. From time to time Noe “commits” and “pushes” the modifications to the “group repository” on GitHub. This will make it possible for her (or Babako) to continue to work at home or at the university later). She just has to remember to “push” the modifications to GitHub at the end of each work session. At some point Noe leaves the campus.
8. Noe arrives at home and want to continue one her laptop. She “pulls” the last modifications from the “group repository” and continue working on her laptop.
9. At anytime Babako can also make a “clone” of the “group repository”. He will get the last version “pushed” by Noe. He can then work in parallel on other issues for instance.
10. To get the last updates from the “group repository”, Noe and Babako “pull” the changes regularly. This allows them to incorporate modifications from each other. Since they are not fluent with git they avoid to modify the same parts of the same file at the same time. This helps avoiding merge conflicts.
11. Deadline is about to arrived. Noe and Babako make sure that all their changes have been pushed to the “group repository” on GitHub. They also double check that the WorkItems has been updated and that they reflects what has been done.
12. The deadline arrives. Nothing has to be delivered: everything is already in the “group repository”. The work of the group is evaluated though the inspection of the content of the “group repository” at the deadline.

The following sections explain how to implement such a typical scenario.

Installing Git¶

To install git on your machine (if not already installed) have a look at the Installing the git toolkit.

Configuring Git¶

You have to configure git once on each machine you use. For instance you may want to configure your account at the university and/or your account on your personal machine.

#---- configure git -------------------------------------------------------
# Attributes with --global goes the .gitconfig file.
# Configure the user associated with contributions (e.g. git push)
git config --global user.name "Noe ZARWIN"
git config --global user.email "noezarwin@users.noreply.github.com"

# Keep the password in memory for 2h
git config --global credential.helper "cache --timeout=7200"
# On some machine this method does not work and you will get an error message
# or a warning after each pull/push. In this case just remove the
# configuration option above using the following command:
#    git config --global --unset credential.helper

# OPTIONAL: Add a proxy ONLY if your machine is behind a firewall
git config --global http.proxy http://www-cache.ujf-grenoble.fr:3128

# OPTIONAL: Configure the editor used to edit message. Depends on the OS
git config --global core.editor "gedit -w -s"  # For ubuntu

# To see current configuration you can use the "git config -l" command
# If you want to change something you can always edit the .gitconfig file
# using the following command (or any editor):
#   git config --global --edit

Cloning the group repository¶

To create a local repository on your machine you have to “clone” your “group repository” (e.g. m2r-aeis-G12) from GitHub. This will create a local repository on your machine where you can work locally.

#---- Clone the "group repository" and into a "local repository" ------------
# Go to your home directory
cd  # On unix

# The "group repository" is at URL like (check this when connected to GitHub)
# https://<github_account>@github.com/<grade>/<grade>-<class>-<group>.git
# The GitHub account is specified explicitly (noezarwin below).
# The following command will ask for the corresponding password.
# Clone it in the current directory.
git clone https://noezarwin@github.com/m2r/m2r-aeis-G12.git
# If you get a message ‘Failed to connect to github.com port 443: Time out’
# it is most probably that your machine is behind a firewall and that
# you need to define http.proxy (see the Configuration section above).
# If you get a message indicating that the repository does not exist
# this can either be due to:
# * an error in the url. Check it again and don't miss .git at the end.
# * a proper read access on the repository might be missing
#   the given login.
#   Check this by connecting to GitHub with this login.

# Enter the newly created directory.
cd m2r-aeis-G12

Two situations are possible here:

• (1) The repository is empty. If you are the first of your group performing this series of steps, your group repository could be empty. There will be at least the ‘.git’ hidden directory. That’s ok. Just continue.
• (2) The repository is initalized. If (an)other(s) member(s) of the group already followed these instructions, your group repository will already contains their work. This is fine. You will get a non-empty directory. There is in particular a .git hidden directory. That’s ok. Just continue.

Simply put, this directory contains the “local repository”. This directory is managed through git commands.

Getting assignment skeletons¶

You now have to configure your repository to get assignment skeletons from the “root repository”. The “root repository” is maintained by teachers. This directory contains work definitions, directory structures, file skeletons, and so on.

#---- Declare the "root directory" and "pull" files from it ---------------
# Declare the m2r-aeis-root as a remote repository.
# You can check that you have access to this repository by logging in
# on GitHub and visiting https://github.com/m2r/m2r-aeis-root .
# You declaration below should be done only once for each local repository.
git remote add root https://noezarwin@github.com/m2r/m2r-aeis-root.git

# If you want to see the list of remote directories use the
# command "git remote -v". If you made a mistake in the URL and need to change
# it use the command "git remote set-url <newurl>".

# "Pull" the assignment skeletons from the "root directory".
# If an editor opens just enter a message like "get assignment skeletons"
git pull root master
# You should now have the assignment skeletons in the local repository.
# Note that if you get an error at this level this could be either because:
# * you've made an error in the url above. Use git remote -v to check it.
#   If there is an error use the following command
#      git remote set-url root <the-url>
# * you do not have read access to this repository. Please check this
#   going on GitHub and check if you see it with your login.

# You can browse the content of the directory with "ls -la" on unix.
# There is one directory per assignment.

Changing CONTRIBUTORS.rst¶

You have to fill the CONTRIBUTORS.rst file in the repository and to put the information about your group using the format such as below.

=== ===== ======= ====================== ======================= ===================== =====================================
 n  group trigram       firstname              lastname              githubAccount                    email
=== ===== ======= ====================== ======================= ===================== =====================================
1   G12   BST     Babako                 SCHMIDT                 babako12              babako.schmidt@e.ujf-grenoble.fr
2   G12   NZN     Noe                    ZARWIN                  noezarwin             noezarwin@gmail.com
=== ===== ======= ====================== ======================= ===================== =====================================

There should be one line for each member. The list must be sorted by lastnames. Spaces and blank lines are important in the RST format.

#---- Edit CONTRIBUTORS.md, commit and push the change --------------------
# Use your favorite editor to edit CONTRIBUTORS.md.
# Enter the data about all group members in the following format.

The fields are the following:

# Save the file.
#
# Add the modified file to the files to be saved in the next commit
git add .

# Commit (e.g. save) the changes to the local repository
git commit -a -m "Set the authors for this repository"

# Push (e.g. publish) the state of the local repository to github
git push origin master
# If you get an error here indicating that there is no such repository
# this could be because you don't have write access to this repository.
# Go to GitHub using the login used in the url and check if you can edit
# files. If not post an issue in the root repository and writing rights
# will be associated to your account.

The changes should now appear on GitHub “group repository”. Log in to GitHub and go to your group repository (e.g. https://github.com/m2gi/m2gi-idm-G12) to check.

Making and pushing changes¶

Time to work and deal with assignments. The process is all about making changes, committing these changes to the “local repository” and pushing these changes on GitHub to the “group repository”.

#---- Making changes, committing and pushing them -------------------------
# Make some changes.

# Check which files have changed.
# Use the "-s" option if you prefer a shorter format.
git status

# Add files to be committed. Replace <files> below by actual file names.
# Use "git add ." to commit the whole directory
git add <files>

# Commit the files (save them in the local repository)
# Provide a useful message instead of <message>.
git commit -a -m ‘<message>’

# OPTIONAL: push changes to the "group repository" on GitHub
# You must do this at the end of a working session if you
# plan to continue on another machine (at home for instance)
# or if you want other group members to "see" the changes.
git push origin master

Pulling changes from the group repo¶

If you work on various machines or if other group members work in parallel your local repository may not contains the last changes available on GitHub in the group repository. In this case you have to “pull” these changes as following.

#---- Pulling changes from the group repository on GitHub -----------------
# Before making a "pull" make sure that you have committed all changes.
# "origin" refers to the "group repository" on GitHub.
# The "pull" command download the latest changes from the "group repository"
# then it try to merge these changes with those made locally.
git pull origin master

Pulling changes may cause some merge conflicts. See resolving merge conflicts in this case.

Pulling changes from the root repo¶

During the course new assignments may be created and/or new material may be added into an existing assignment, for instance to bring precision to some tasks or to add additional skeletons. These changes will be made available through the “root repository” which contains assignment skeletons. In order to get last updates you just have to pull these changes in the same way you pull changes from your “group repository”.

# Before making a "pull" make sure that you have committed all changes.
# "root" refers to the "root repository" on GitHub.
# This "remote" repository has been declared in the "Getting assignment skeletons"
# section.
git pull root master

Pulling changes may cause some merge conflicts. See resolving merge conflicts in this case.

Staying informed¶

In GitHub terms, “Watching” a repository means receiving notification when changes occur to it.

Since you are member of your “group repository” you should automatically receive notifications for new commits for instance. This is handy to keep in synch with other group members. By default you “Watch” this repository but you can change this by pressing on the “Unwatch” button on GitHub.

If you want to stay informed you may also want to “Watch” the following repositories.

• the “info” repository for general information about the course. This can be useful to get notified when new slides are added for instance.
• the “root” repository. Register to this repository if you want to receive information about assignments, get notification when questions are posted, etc.

Questions/Bugs/...?¶

If you found a bug in an assignement, if you have some comments or or have a question about the course please post an [GitHub issue](https://guides.github.com/features/issues/).

Please select the repository that is most suited to your issue:

• If the “issue” is general or related to a particular assignment and the question/issue is relevant to other groups, then post the issue in “root” repository.
• If the “issue” is only related to your group (you and other group member partner) please post the issue in your “group” repository (m2r-aeis-G12 for instance). Use the (!) button in the web interface (see [create an issue](https://guides.github.com/features/issues/) for details).

If you have some answer to some posted issues, please provide it directly online.

Features¶

ReadTheDocs provide the following services: * hosting of documentation of open source projects * continuous Sphinx generation (connected to GitHub) * management of documentation versioning within the browser * support for downloading documentation in html, pdf, and e-pub formats * searchable documentation

Installation¶

No installation is required as this service is on the cloud. However you must create an ReadTheDocs account.

Then you need to connect this account with your GitHub account. Once this is done you can import the projects that have sphinx documentation.

Usage¶

Once the ReadTheDocs and GitHub account are connected, the documentation pushed on the github repository is automatically compiled and published on the ReadTheDpcs web site.

It is worth to use the sphinx rtd theme as it provides an excellent rendering both on computer screens but also on tablet or smart phones.

sphinx rtd theme

Documentation¶

The web site is rather easy to use, but if you need documentation for specific topics you can have a look at ReadTheDocs documentation.

Installation¶

Documentation¶

Documentation¶

TravisCI could be configured for repositories based on a given list of programming languages. This includes in particular:

• documentation for Python
• documentation for Java

Installation¶

One should distinguish two java components:

• JRE: The Java Runtime Environment enables end-users to execute java programs.
• JDK: The Java Development Toolkit allows developers to develop java programs.

The JRE can be installed and used independently from the JDK. By contrast, the JDK comes usually with a JRE. Here are short instructions to install the JDK (including the JRE). More information is available on the java installation guide:

On Windows:

• Download the jdk from the java download page.

• Create the following directory structure:

  %SCRIBESTOOLS%
      Java
          jre
          jdk
  

• Install the JDK in %SCRIBESTOOLS%\Java\JDK and the JRE in %SCRIBESTOOLS%\Java\jdk

• Add the following directory to the system PATH:

  %SCRIBESTOOLS%\Java\jdk\bin
  

• Set the JAVA_HOME environment variable to:

  %SCRIBESTOOLS%\Java\jdk
  

On Ubuntu:

# Remove existing OpenJDK
sudo apt-get purge openjdk*
# Install Oracle Java 8
# if add-apt-repository is missing in the next command
#     sudo apt-get install software-properties-common
#     sudo apt-get install python-software-properties
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
# Set Java Environment Variable
sudo apt-get install oracle-java8-set-default

If this does not work try instead to follow the instructions how to install oracle java 9 in debian.

Launching Java¶

To test the JRE type the following command:

java -version

To test the JDK type the:

javac -version

Installation¶

This section shows how to install Python 2.7, how to use create virtual environments, how to install necessary libraries including windows specific libraries. If you want to use Jython/Python in the context of modelio (see Modelio) you do not have anything to install as Jython 2.7 is embedded into this tool.

pip install virtualenvwrapper-win   # on windows
pip install virtualenvwrapper       # otherwise

mkdir %SCRIBESTOOLS%\PyVEnvs27

# define WORKON_HOME variable as %SCRIBESTOOLS%\PyVEnvs27

mkvirtualenv ScribeEnv
# this creates a directory ``%SCRIBESTOOLS%\PyVEnvs27\ScribeEnv``.
# You should also see that the prompt of the shell is now prefixed with
# (ScribeEnv) like in the following line:
# (ScribeEnv) C:\Users\jmfavre>

workon ScribeEnv

pip install XXXX\requirements-windows.txt

sudo apt-get install autoconf g++ python2.7-dev python-dev
sudo apt-get build-dep python-imaging                                                    # for Pillow package
sudo apt-get install libjpeg8 libjpeg62-dev libfreetype6 libfreetype6-dev                # for Pillow package
sudo apt-get install libffi-dev libssl-dev libxml2-dev libxslt1-dev

sudo /<path-to-yout-virtual-env>/bin/pip install requirements-ubuntu.txt

Launching Python¶

To test your python installation try the following command:

python -V

Documentation¶

The best way to find information about python is just to ask question such as “python read file at once” on google. You may also want to have a look at J/Python in a nutshell and print a cheat sheet :

• CheatSheetA
• CheatSheetB
• CheatSheetC
• FrenchCheatSheetD
• RegExCheatSheet

Overview¶

Python being a dynamic language, using an IDE is a really good idea. This will help you find errors at development time rather that at runtime. There are various IDE for pythons around (see python IDE comparison).

If you are going to write non trival python programs for some time, then we recommend using PyCharm. It will save you time. PyCharm is usually faster, simpler and more powerful than PyDev, the python environment on eclipse. If you are really a huge fan of eclipse, you might prefer PyDev indeed.

Installation¶

There are two versions:

• An open source version which is quite complete and very useful.
• A commercial version which has support for django, databases, etc.

• download PyCharm page and then download the appropriate version (e.g. Windows community edition (web), Windows commercial edition (web)).

• install the version downloaded in a directory like %SCRIBESTOOLS%\PyCharmOpen or %SCRIBESTOOLS%\PyCharmCommercial. This naming schema allows to have both editions installed at the same time.

• by default your personal configuration of PyCharm goes in a directory like .PyCharm in your home directory, but if you want you can change this by editing the file bin/idea.properties in the installation directory. You have to adjust for instance the following two lines:

  idea.config.path=Z:/.PyCharm50/config
  idea.system.path=Z:/.PyCharm50/system
  

Launching PyCharm¶

The installer most likely created a shortcut. Click on it to launch PyCharm. Alternatively you can also find the executable in the bin directory of the installation or in a standard bin directory (e.g. /usr/bin/pycharm).

Documentation¶

Documentation is available from the help menu of the tool.

Configuration¶

To configure PyCharm use the menu File > Settings:

Editor
    File Encodings
        UTF8
    Appearance
        Show line numbers
        Show method separators
Code Style
    General
        right margin (columns)

Features¶

Django at Glance gives an idea about django development.

Installation¶

Django is based on python. Follow the instructions in the Installation section if not already done. These instructions install python but also Django as well as many useful Django components.

workon ScribeEnv

Launching Django¶

If you want to check that Django is installed you can try the following:

workon ScribeEnv
python -c "import django; print(django.get_version())"
django-admin --version

Documentation¶

In the open source community Django is reknown for the quality of its documentation. After reading Django at Glance the best way to start is to read the Django Tutorial.

Installation¶

• download the “command line shell” for “sqlite3” from SQLite download page. For Windows download sqlite-shell-win32-x86-3081002.zip web.
• create a directory where you want to install sqlite3 (e.g. %SCRIBESTOOLS%\SQLite)
• extract the archive (only one file on windows: sqlite3.exe)
• move the content of the archive to the directory created
• add %SCRIBESTOOLS%\SQLite to the path.

On Ubuntu you can install SQLite as following:

sudo apt-get install sqlite3

Launching SQLite¶

You can test the installation and check the version of sqlite3 with the following command:

sqlite3 -version

Then try:

sqlite3

This should launch the SQLite shell. Try the following commands:

.help
.schema
.quit

Since no database has been specified when launching the shell command the .schema command will not display anything.

Sqlite3 for django¶

If you use SQLite with django, then you can launch the shell with the following commands:

python manage.py dbshell

Documentation¶

The documentation is available online (SQLite documentation).

• SQLite dialect.
• SQL features omitted from SQLite

To get some help about the command line type:

sqlite3 -help

If you want some brief help about the shell commands (including SQL) you can type in the shell:

.help

More generally, the documentation of the shell is available at https://www.sqlite.org/cli.html

Installation¶

On Ubuntu you can install MySQL as following:

sudo apt-get install mysql-server

For more details you can have a look at this short tutorial.

Documentation¶

The documentation is available online (MySQL documentation).

Installation¶

• download the installer for your operating system the download page.

  On Windows graphviz-2.38.msi must be used, at least if you plan to use the pygraphviz windows library for python web.

  On Ubuntu Graphviz can be installed via:

  apt-get install graphviz libgraphviz-dev pkg-config
  

• install the program in a directory like %SCRIBESTOOLS%\Graphviz\

• add %SCRIBESTOOLS%\Graphviz\ into the PATH environment variable.

Launching Graphviz¶

To test your installation type the following command in a new shell. It should display the version of graphviz.

dot -V

You can try the gvedit, a very simple graphical interface. It is not really useful though as Graphviz is mostly used by other programs.

gvedit

Documentation¶

There is a lot of documentation.

Installation¶

Sphinx is written in Python. Follow the instructions in the Installation section. This will install Python as well as Sphinx and related components.

workon ScribeEnv

Launching Sphinx¶

To try the installation of Sphinx type the following command and press Ctrl-C to exit from the program:

sphinx-quickstart

Documentation¶

An extensive documentation is available on the Sphinx and rst web sites. To learn rst different kinds of resources are probably better:

• Examples. The best way to learn rst is probably to look at the source of existing rst texts. For instance on ReadTheDocs the documentation usually include a link View Code on the top-left corner of each page.

• Cheat Sheets Here is a list of cheat sheets ordered approximatively by size.

  • CheatSheet #1
  • CheatSheet #2
  • CheatSheet #3
  • CheatSheet #4

• Nice pages. Some interesting pages from Sphinx documentation:

  • reStructuredText Primer: a extended introduction
  • Sphinx Markup Constructs: a rather easy-to-use reference

If you have already some knowledge about markdown you may be interested by Markdown vs. rst comparison.

Extensions¶

• sphinx-contrib
• awesome-sphinx
• sphinxext-survey

Changing the PATH¶

There are different ways to change the PATH variable on windows and these techniques depends on the version of windows. Please have a look at this note (web) for instance.

Installation¶

If you use some editors like LibreOffice you might be interested in installing True Type Font available on Windows. This will bring “Arial” and “Times New Roman” for instance. Otherwise you might have problems when vizualizing document on Windows and Ubuntu.

sudo apt-get install ttf-mscorefonts-installer