Difference between revisions of "Setting Up Your Development Environment"

From wiki.gpii
Jump to: navigation, search
m (Dependencies)
m
 
(24 intermediate revisions by 9 users not shown)
Line 1: Line 1:
'''Notes''':  
+
'''Note''': These instructions are for developers of the GPII. '''Simpler instructions for [[Installing the GPII]]''' for use are also available.
* These instructions are for developers of the GPII. '''Simpler instructions for [[Installing the GPII]]''' for use are also available.
 
* Installation instructions specific to Cloud4all's second pilot phase are available at [[Cloud4all Pilot 2 - Set up and installation]].
 
* Installation instructions specific to Cloud4all's third pilot phase will be made available at [[Cloud4all Pilot 3 - Set up and installation]].
 
 
 
  
 
= Getting Set Up For GPII Personalization Framework Development =
 
= Getting Set Up For GPII Personalization Framework Development =
Line 15: Line 11:
  
 
== Supported Configurations ==
 
== Supported Configurations ==
 +
 +
It is possible to automatically create development VMs with minimal effort using tools such as [https://www.vagrantup.com/ Vagrant]. The following links lead to instructions for either platform:
 +
* [https://github.com/gpii/linux/#setting-up-a-virtual-machine Linux]
 +
* [https://github.com/gpii/windows#test-vm Windows]
 +
 +
If manual setup methods are preferred then please use the remaining instructions on this page.
 +
 +
=== Versions to Use ===
 +
 +
The definitive definition of the platform requirements for the GPII are given in the provisioning file held at https://github.com/GPII/universal/blob/master/provisioning/vars.yml#L11. At the time of writing these are node.js 6.x LTS and its corresponding version of npm 3.x The instructions in this file for manual installation are only maintained on a "best efforts" basis and should not be depended on.
  
 
=== Fedora Installation Instructions ===
 
=== Fedora Installation Instructions ===
  
 
#Download Fedora:
 
#Download Fedora:
#*Fedora 19 64-bit: [http://archive.fedoraproject.org/pub/fedora/linux/releases/19/Live/x86_64/Fedora-Live-Desktop-x86_64-19-1.iso Fedora 19 Live Desktop ISO image] or, for the latest version, use Fedora 20 [http://archive.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso Fedora 20 Live Desktop ISO Image]
+
#*Fedora 19 64-bit: [http://archive.fedoraproject.org/pub/fedora/linux/releases/19/Live/x86_64/Fedora-Live-Desktop-x86_64-19-1.iso Fedora 19 Live Desktop ISO image] or, for the latest version, see the "[https://getfedora.org/en/workstation/download/ Download Fedora Desktop"] page.
 
#Install it:
 
#Install it:
 
#*From a Live CD, choose '''Applications''' > '''System Tools''' > '''Install to Hard Drive'''
 
#*From a Live CD, choose '''Applications''' > '''System Tools''' > '''Install to Hard Drive'''
Line 26: Line 32:
  
 
==== Package Dependencies ====
 
==== Package Dependencies ====
 +
 +
Beginning with Fedora 22, <code>dnf</code> has replaced <code>yum</code> as the native package manager. The older <code>yum</code> commands remain here for those using older versions of Fedora.
 +
<pre>sudo dnf install kernel-devel kernel-headers dkms gcc gcc-c++ \
 +
  git openssl-devel glib-devel glib2-devel gtk3-devel \
 +
  pcsc-lite-devel pcsc-lite pcsc-perl alsa-lib-devel libXrender-devel \
 +
  libXrandr-devel libX11-devel xorg-x11-proto-devel PackageKit-glib-devel json-glib-devel
 +
</pre>
 +
 +
For pre Fedora 22:
 
<pre>sudo yum install kernel-devel kernel-headers dkms gcc gcc-c++ \
 
<pre>sudo yum install kernel-devel kernel-headers dkms gcc gcc-c++ \
 
   git openssl-devel glib-devel glib2-devel gtk3-devel \
 
   git openssl-devel glib-devel glib2-devel gtk3-devel \
 
   pcsc-lite-devel pcsc-lite pcsc-perl alsa-lib-devel libXrender-devel \
 
   pcsc-lite-devel pcsc-lite pcsc-perl alsa-lib-devel libXrender-devel \
   libXrandr-devel libX11-devel xorg-x11-proto-devel
+
   libXrandr-devel libX11-devel xorg-x11-proto-devel PackageKit-glib-devel json-glib-devel
 
</pre>
 
</pre>
  
 
==== Node.js ====
 
==== Node.js ====
<pre>
+
<pre>sudo dnf install nodejs nodejs-devel npm node-gyp nodejs-docs nodejs-debug
sudo yum install nodejs nodejs-devel npm node-gyp nodejs-docs nodejs-debug
+
</pre>
 +
 
 +
Pre Fedora 22:
 +
<pre>sudo yum install nodejs nodejs-devel npm node-gyp nodejs-docs nodejs-debug
 
</pre>
 
</pre>
  
Line 40: Line 58:
  
 
#Google Chrome
 
#Google Chrome
## Download the browser from [https://www.google.com/chrome/index.html https://www.google.com/chrome/index.html]. When you choose the rpm version using Firefox, the browser will offer the option to install the package immediately.
+
##Download the browser from [https://www.google.com/chrome/index.html https://www.google.com/chrome/index.html]. When you choose the rpm version using Firefox, the browser will offer the option to install the package immediately.
  
 
==== RFID User Listener ====
 
==== RFID User Listener ====
Line 59: Line 77:
 
./pcsc_scan
 
./pcsc_scan
 
</pre>
 
</pre>
 +
 
We also include a utility for reading and writing the tokens on smart cards.
 
We also include a utility for reading and writing the tokens on smart cards.
 
<pre># If you haven't started the daemon already do so.
 
<pre># If you haven't started the daemon already do so.
Line 72: Line 91:
 
python pcscutil.py set gpiitoken nisha
 
python pcscutil.py set gpiitoken nisha
 
</pre>
 
</pre>
 +
  
  
Line 77: Line 97:
  
 
First, clone the GPII Linux repository.
 
First, clone the GPII Linux repository.
 
+
<pre>git clone git://github.com/GPII/linux.git
<pre>
 
git clone git://github.com/GPII/linux.git
 
 
cd linux
 
cd linux
 
</pre>
 
</pre>
  
 
We use the grunt task system to perform our build operations. If you don't have grunt installed yet you can do so with:
 
We use the grunt task system to perform our build operations. If you don't have grunt installed yet you can do so with:
 
+
<pre>sudo npm install -g grunt-cli</pre>
<pre>npm install -g grunt-cli</pre>
 
  
 
To fetch our core universal dependencies and build the linux specific plugins run (note that the 'grunt build' below will install the GPII USB listener software for Linux/Fedora):
 
To fetch our core universal dependencies and build the linux specific plugins run (note that the 'grunt build' below will install the GPII USB listener software for Linux/Fedora):
 
+
<pre>npm install
<pre>
 
npm install
 
 
grunt build
 
grunt build
 
</pre>
 
</pre>
  
 
Because the history of the universal repository is quite large, it can take a long time to clone (and sometimes will fail depending on the network). To check it out faster for testing use the fastClone option. Note however, you will need the regular build in order to commit code and push on universal.
 
Because the history of the universal repository is quite large, it can take a long time to clone (and sometimes will fail depending on the network). To check it out faster for testing use the fastClone option. Note however, you will need the regular build in order to commit code and push on universal.
 +
<pre>grunt build --fastClone</pre>
  
<pre>grunt build --fastClone</pre>
 
 
 
To clean the plugin binaries use
 
To clean the plugin binaries use
 +
<pre>grunt clean</pre>
  
<pre>grunt clean</pre>
 
 
'''Note that after the execution of the clean task the system won't work, so you have to skip this step if you're installing the GPII.'''
 
'''Note that after the execution of the clean task the system won't work, so you have to skip this step if you're installing the GPII.'''
  
 
You can start the GPII local server on port 8080 using:
 
You can start the GPII local server on port 8080 using:
 
+
<pre>node gpii.js</pre>
<pre>grunt start</pre>
 
  
 
To install and uninstall the listener components use the following. Note that this may prompt you for sudo access.
 
To install and uninstall the listener components use the following. Note that this may prompt you for sudo access.
 
+
<pre>grunt install
<pre>
 
grunt install
 
 
grunt uninstall
 
grunt uninstall
 
</pre>
 
</pre>
  
 
To run the GPII USB listener, execute the command:
 
To run the GPII USB listener, execute the command:
<pre>
+
<pre>$ gpii-usb-user-listener
$ gpii-usb-user-listener
 
 
</pre>
 
</pre>
  
You may see an error when you run the above, namely: "<code>ImportError: No module named httplib2</code>". If so, execute the following command to install the httplib2 library, and then execute <code>sudo gpii-usb-user-listener</code> again:
+
You may see an error when you run the above, namely: "<code>ImportError: No module named httplib2</code>". If so, execute the following command to install the httplib2 library, and then execute <code>sudo gpii-usb-user-listener</code> again:
 
+
<pre>$ sudo dnf install python-httplib2 python3-httplib2
<pre>
+
</pre>
$ sudo yum install python-httplib2 python3-httplib2
+
Pre Fedora 22:
 +
<pre>$ sudo yum install python-httplib2 python3-httplib2
 
</pre>
 
</pre>
  
Line 148: Line 159:
 
*Git
 
*Git
 
**Install [https://windows.github.com/ GitHub for Windows] - it includes the command line [http://msysgit.github.com Msysgit] which you run as "Git Shell".
 
**Install [https://windows.github.com/ GitHub for Windows] - it includes the command line [http://msysgit.github.com Msysgit] which you run as "Git Shell".
**Or, for advanced developers, use [http://www.cygwin.com/ Cygwin] for a full Unix-like environment on Windows
+
**Or, for advanced developers, use [http://www.cygwin.com/ Cygwin] for a full Unix-like environment on Windows - note that this will expose you to many annoyances and oddities with, for example, file permissions, or the use of git by npm
  
 
*Node.js
 
*Node.js
**Next you need to install Node.js. Go to http://nodejs.org/download/ and download the latest '''32-bit''' version of v0.10.xx (this was tested with v0.10.38)
+
**Next you need to install Node.js. Go to [http://nodejs.org/download/ http://nodejs.org/download/] and download the latest version of v4.4.xx LTS (this was tested with [https://nodejs.org/dist/v4.4.7/ v4.4.7]). You should install the version (32-bit or 64-bit) which matches the bitness of your operating system.
*** if you see an error ''FATAL ERROR: Uncaught exception: %1 is not a valid Win32 application.'' you probably have the 64-bit version of Node.js.
 
 
**Troubleshooting:
 
**Troubleshooting:
***Node v0.10.xx has a bug with the installer, the folder %APPDATA%\npm doesn't get created. If you see an error like: "Error: ENOENT, stat 'C:\Users\<USERNAME>\AppData\Roaming\npm'" on install or when trying to run npm, simply create the folder by typing "mkdir %APPDATA%\npm"
+
***Node does not always appear on the path (so will not run in command line) until you re-login or restart Windows.
***to ensure nodejs folder is on the path ("echo %PATH%") and add it before nodejs\node_modules\npm if required.
 
 
***Note: you can easily switch between different versions of Node.js using [https://github.com/hakobera/nvmw nvmw (Simple Node Manager for Windows)].
 
***Note: you can easily switch between different versions of Node.js using [https://github.com/hakobera/nvmw nvmw (Simple Node Manager for Windows)].
 
+
* Download and install [https://www.python.org/ Python] (e.g. Python 2.7.x).
* VisualStudio - only required to build the Listeners for Windows, most developers don't need this (even if they want to use the listeners)
+
*VisualStudio - all developers require this in order to build any native modules in the npm tree - in practice only the C/C++ tools are necessary unless you want to build user listeners in which case C# support is also required.
** Download and install [http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop VisualStudio Express 2013 for Windows Desktop] or the more full featured [http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#DownloadFamilies_2 Visual Studio 2013 Community].
+
**Download and install [http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop VisualStudio Express 2013 for Windows Desktop] or the more full featured [http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#DownloadFamilies_2 Visual Studio 2013 Community].
  
 
Other:
 
Other:
  
 
*Windows 7 has a bug with high-contrast mode in the '''64-bit version'''. If you're running this Windows version, you'll need to install the hotfix linked from this [http://support.microsoft.com/kb/2516889 Microsoft support page] (x64 only).
 
*Windows 7 has a bug with high-contrast mode in the '''64-bit version'''. If you're running this Windows version, you'll need to install the hotfix linked from this [http://support.microsoft.com/kb/2516889 Microsoft support page] (x64 only).
 +
*Note that Windows 7 is not currently a supported and maintained platform for the GPII on Windows. Our support primarily is for Windows 10, with lower level support for Windows 8.1 and Windows 8
  
 
==== Building and Starting the GPII Personalization Framework on Windows ====
 
==== Building and Starting the GPII Personalization Framework on Windows ====
  
*Open up a git compatible command prompt (eg. git shell)
+
*Open up a git compatible command prompt (e.g. git shell)
 
*Create a GPII directory
 
*Create a GPII directory
**<code>mkdir c:\gpii</code> (or wherever you prefer)
+
**<code>mkdir /c/gpii</code> (or wherever you prefer)
**<code>cd c:\gpii</code>  
+
**<code>cd /c/gpii</code>
 
*Clone the GPII Windows repository
 
*Clone the GPII Windows repository
**<code>git clone <nowiki>git://github.com/GPII/windows.git</nowiki></code>  
+
**<code>git clone <nowiki>git://github.com/GPII/windows.git</nowiki>&nbsp;</code>
**<code>cd windows</code>  
+
*<code>cd windows</code>
 
*Install dependencies of the framework
 
*Install dependencies of the framework
**<code>npm install --ignore-scripts=true</code>  
+
**<code>npm install</code>
 
***If this step fails, please check the [[#Troubleshooting|troubleshooting section]].
 
***If this step fails, please check the [[#Troubleshooting|troubleshooting section]].
 
*Make sure grunt is installed:
 
*Make sure grunt is installed:
** <code>npm install grunt</code>  
+
**<code>npm install grunt</code>
** <code>npm install -g grunt-cli</code>  
+
**<code>npm install -g grunt-cli</code>
 
*Build:
 
*Build:
**<code>grunt build</code>  
+
**<code>grunt build</code>
 
*Start the GPII Framework by running the following command in the <code>gpii\windows</code> folder:
 
*Start the GPII Framework by running the following command in the <code>gpii\windows</code> folder:
**<code>grunt start</code>
+
**<code>node gpii.js</code>
  
 
==== Installing the USB and RFID listeners ====
 
==== Installing the USB and RFID listeners ====
Line 191: Line 201:
 
==== Additional Windows Configuration ====
 
==== Additional Windows Configuration ====
  
*On Windows 7, the GPII cannot kill applications using taskill unless you change the user account control settings:
 
**Go into Control Panels > User Accounts and Family Safety > User Accounts > User Account Control Settings
 
**Set the notification level to "Never notify".
 
**You need to reboot Windows to apply this setting.
 
 
*The Magnifier may be set to change magnification in steps of 100% by default. In order to enable smaller steps, start the Magnifier, open the Options (the cogwheel icon) and change the slider to 25%.
 
*The Magnifier may be set to change magnification in steps of 100% by default. In order to enable smaller steps, start the Magnifier, open the Options (the cogwheel icon) and change the slider to 25%.
* The following is optional but useful if you want to report back on bugs:  
+
*The following is optional but useful if you want to report back on bugs:
** Open a command line and right-click on the command line's window.
+
**Open a command line and right-click on the command line's window.
** In the context menu that pops up, select the "Layout" tab.
+
**In the context menu that pops up, select the "Layout" tab.
** In the layout tab, change the "Height" of the "Screen Buffer Size" to a much higher number, e.g. 900. Then click OK to confirm the change.
+
**In the layout tab, change the "Height" of the "Screen Buffer Size" to a much higher number, e.g. 900. Then click OK to confirm the change.
** As a result of this, most of the DOS windows that pop up when you start GPII will "store" more logging lines. These logging lines can be copied and pasted into bug reports. For guidance on how to copy those logging lines, see Microsoft's article [http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/windows_dos_copy.mspx?mfr=true To copy text from a command prompt window].
+
**As a result of this, most of the DOS windows that pop up when you start GPII will "store" more logging lines. These logging lines can be copied and pasted into bug reports. For guidance on how to copy those logging lines, see Microsoft's article [http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/windows_dos_copy.mspx?mfr=true To copy text from a command prompt window].
  
 
== Troubleshooting ==
 
== Troubleshooting ==
  
 
=== test without usb ===
 
=== test without usb ===
Once you start the system (by using the <code>grunt start</code>/<code>start.sh</code> scripts), you can test it without USB by navigating your browser to the following URLs:
 
  
* <code>http://localhost:8081/user/sammy/login</code>
+
Once you start the system (by using the <code>node gpii.js</code> command), you can test it without USB by navigating your browser to the following URLs:
* <code>http://localhost:8081/user/sammy/logout</code>
+
 
 +
*<code>[http://localhost:8081/user/sammy/login http://localhost:8081/user/sammy/login]</code>
 +
*<code>[http://localhost:8081/user/sammy/logout http://localhost:8081/user/sammy/logout]</code>
 +
 
 +
With a version updated after 2015-10-09 you can also use:
  
 +
*<code>[http://localhost:8081/user/sammy/logonChange http://localhost:8081/user/sammy/logonChange]</code>
  
 
=== get a list of currently logged in tokens ===
 
=== get a list of currently logged in tokens ===
You can get a list of currently logged in tokens using the following URL:
 
* <code>http://localhost:8081/userToken</code>
 
  
'''Note''': When you use <code>localhost:8081</code> to log in tokens, you need to use the same host to get the list of tokens. When you use <code>127.0.0.1:8081</code> to log in tokens, you need to use <code>http://127.0.0.1:8081/userToken</code>.
+
You can get a list of currently logged in tokens using the following URL:
 +
 
 +
*<code>[http://localhost:8081/userToken http://localhost:8081/userToken]</code>
 +
 
 +
'''Note''': When you use <code>localhost:8081</code> to log in tokens, you need to use the same host to get the list of tokens. When you use <code>127.0.0.1:8081</code> to log in tokens, you need to use <code>[http://127.0.0.1:8081/userToken http://127.0.0.1:8081/userToken]</code>.
  
 
=== run acceptance tests ===
 
=== run acceptance tests ===
You should also '''run the [[Writing Acceptance Tests|automated tests]]''', especially before and after commits. To run the automated tests, go to the directory <code>universal</code> and run the following command:
+
 
* <code>node tests\all-tests.js</code>
+
You should also '''run the [[Writing_Acceptance_Tests|automated tests]]''', especially before and after commits. To run the automated tests, go to the directory <code>universal</code> and run the following command:
The output in the terminal should end with a line that says something like <code> jq:&nbsp; All tests concluded: 58/58 total tests passed in 6798 ms - PASS</code>.
+
 
 +
*<code>node tests\all-tests.js</code>
 +
 
 +
The output in the terminal should end with a line that says something like <code>jq:&nbsp; All tests concluded: 58/58 total tests passed in 6798 ms - PASS</code>.
 +
 
  
  
 
=== build.cmd vs grunt build ===
 
=== build.cmd vs grunt build ===
 +
 
'''Windows build (<code>build.cmd</code>) errors'''
 
'''Windows build (<code>build.cmd</code>) errors'''
  
Line 231: Line 248:
  
 
You should also avoid renaming this folder by extending its name to e.g. <code>npm-cache-old</code> because this would still cause build errors. This build issue may occur when you install the GPII framework on a Windows computer where an older version of GPII was installed in the past.
 
You should also avoid renaming this folder by extending its name to e.g. <code>npm-cache-old</code> because this would still cause build errors. This build issue may occur when you install the GPII framework on a Windows computer where an older version of GPII was installed in the past.
 
===updating node and npm versions===
 
 
If you had other versions of node.js and npm in your system and update manually to node.js 0.8.25 then the npm version will be stuck to 1.2.30, thus making the npm install --ignore-scripts=true fail on Windows.
 
 
To be able to update npm and get the npm install working:
 
 
* Node.js 0.8.25 32-bit
 
* Delete the npm that comes with that version of Node
 
** C:\Program Files (x86)\nodejs\npm
 
** C:\Program Files (x86)\nodejs\npm.cmd
 
** C:\Program Files (x86)\nodejs\node_modules\npm
 
* Grab npm 1.4.9 from http://nodejs.org/dist/npm/
 
* Copy the npm 1.4.9 files into C:\Program Files (x86)\nodejs
 
* Now we have a working recent npm and we can use npm to update itself: npm install -g npm (need to run as an Administrator)
 
* npm install -g grunt-cli
 
  
 
== Unsupported Configurations ==
 
== Unsupported Configurations ==
Line 255: Line 256:
  
 
Use 'sudo apt-get install' to install the following packages:
 
Use 'sudo apt-get install' to install the following packages:
<pre>
+
<pre>sudo apt-get install git g++ curl libglib2.0-dev libasound2-dev libxrender-dev libxrandr-dev pcscd
sudo apt-get install git g++ curl libglib2.0-dev libasound2-dev libxrender-dev libxrandr-dev pcscd
 
 
</pre>
 
</pre>
  
 
The version of Node.js distributed in the Ubuntu package repository is very out of date. Instead, use the [https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager Installing Node.js via package manager] instructions on to the Node.js wiki or build from source.
 
The version of Node.js distributed in the Ubuntu package repository is very out of date. Instead, use the [https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager Installing Node.js via package manager] instructions on to the Node.js wiki or build from source.
<pre>
+
<pre>sudo apt-get update
sudo apt-get update
 
 
sudo apt-get install -y python-software-properties python g++ make
 
sudo apt-get install -y python-software-properties python g++ make
 
sudo add-apt-repository -y ppa:chris-lea/node.js
 
sudo add-apt-repository -y ppa:chris-lea/node.js
Line 269: Line 268:
  
 
Or build it from source:
 
Or build it from source:
 
+
<pre> wget http://nodejs.org/dist/v0.10.23/node-v0.10.23.tar.gz
<pre>
 
  wget http://nodejs.org/dist/v0.10.23/node-v0.10.23.tar.gz
 
 
   tar -xvzf node-v0.10.23.tar.gz
 
   tar -xvzf node-v0.10.23.tar.gz
 
   cd node-v0.10.23
 
   cd node-v0.10.23
Line 289: Line 286:
  
 
   You can either:
 
   You can either:
  [https://www.google.com/chrome/index.html Download the installer]
+
[https://www.google.com/chrome/index.html Download the installer]
  OR
+
OR
  use 'sudo apt-get install google-chrome-stable'
+
use 'sudo apt-get install google-chrome-stable'
  
 
==== RFID User Listener ====
 
==== RFID User Listener ====
Line 301: Line 298:
 
Covering the installation of the universal package and node.js.
 
Covering the installation of the universal package and node.js.
  
<span style="color:#ff0000;">'''The Mac installation doesn't do much yet except running gpii in node.js. There are no settings handlers or listeners implemented yet, so only the http GET or POST requests will work.'''</span>
+
<span style="color:#ff0000">'''The Mac installation doesn't do much yet except running gpii in node.js. There are no settings handlers or listeners implemented yet, so only the http GET or POST requests will work.'''</span>
  
 
*Installing make: The make compiler is not automatically included in a Mac, but is included in the Xcode development package.
 
*Installing make: The make compiler is not automatically included in a Mac, but is included in the Xcode development package.
Line 314: Line 311:
 
make
 
make
 
sudo make install</pre>
 
sudo make install</pre>
 +
 
*Install GPII Universal
 
*Install GPII Universal
  
 
(to be tested.)
 
(to be tested.)
 
<pre>git clone git://github.com/GPII/universal.git</pre>
 
<pre>git clone git://github.com/GPII/universal.git</pre>
 +
 
finally you need to mimic the structure in the git gpii linux version.
 
finally you need to mimic the structure in the git gpii linux version.
  
Line 328: Line 327:
 
-- universal  
 
-- universal  
 
</pre>
 
</pre>
 +
 
*the index.js file needs to be created and for the beginning can contain
 
*the index.js file needs to be created and for the beginning can contain
 
<pre>/*!
 
<pre>/*!
Line 351: Line 351:
 
});
 
});
 
</pre>
 
</pre>
 +
 
*the "universal" folder is the recently downloaded folder from github, containing all the downloaded files.
 
*the "universal" folder is the recently downloaded folder from github, containing all the downloaded files.
 
*open the terminal and go to the just created index.js file. run:
 
*open the terminal and go to the just created index.js file. run:
 
<pre>node index.js
 
<pre>node index.js
 
</pre>
 
</pre>
 +
 
Well done, this will start the node.js server and make gpii running and listening. The Port number on which it is listening should be shown in the second-last output line, like this:
 
Well done, this will start the node.js server and make gpii running and listening. The Port number on which it is listening should be shown in the second-last output line, like this:
 
<pre>...
 
<pre>...
Line 362: Line 364:
 
13:04:25.789:  Cleared instantiators (last id 9c0m8p6e-8) from threadLocal for end of flowManager.preferencesServer.solutionsRegistry.deviceReporter.matchMaker.ontologyServer.development
 
13:04:25.789:  Cleared instantiators (last id 9c0m8p6e-8) from threadLocal for end of flowManager.preferencesServer.solutionsRegistry.deviceReporter.matchMaker.ontologyServer.development
 
</pre>
 
</pre>
 
 
 
[[Category:GPII Architecture]]
 
[[Category:GPII Architecture]]

Latest revision as of 14:06, 2 March 2017

Note: These instructions are for developers of the GPII. Simpler instructions for Installing the GPII for use are also available.

Getting Set Up For GPII Personalization Framework Development

We are currently developing the GPII Personalization Framework on two platforms:

  • Linux with GNOME 3
  • Windows

The core of the GPII personalization framework is fully cross-platform. It is written in JavaScript and deployed in the Node.js runtime environment, which is widely supported on Windows, Linux, Mac OS X, and even some mobile systems.

Supported Configurations

It is possible to automatically create development VMs with minimal effort using tools such as Vagrant. The following links lead to instructions for either platform:

If manual setup methods are preferred then please use the remaining instructions on this page.

Versions to Use

The definitive definition of the platform requirements for the GPII are given in the provisioning file held at https://github.com/GPII/universal/blob/master/provisioning/vars.yml#L11. At the time of writing these are node.js 6.x LTS and its corresponding version of npm 3.x The instructions in this file for manual installation are only maintained on a "best efforts" basis and should not be depended on.

Fedora Installation Instructions

  1. Download Fedora:
  2. Install it:
    • From a Live CD, choose Applications > System Tools > Install to Hard Drive
    • From an Install ISO, choose Activities > Install to Hard Drive
  3. Follow the installation steps

Package Dependencies

Beginning with Fedora 22, dnf has replaced yum as the native package manager. The older yum commands remain here for those using older versions of Fedora.

sudo dnf install kernel-devel kernel-headers dkms gcc gcc-c++ \
  git openssl-devel glib-devel glib2-devel gtk3-devel \
  pcsc-lite-devel pcsc-lite pcsc-perl alsa-lib-devel libXrender-devel \
  libXrandr-devel libX11-devel xorg-x11-proto-devel PackageKit-glib-devel json-glib-devel

For pre Fedora 22:

sudo yum install kernel-devel kernel-headers dkms gcc gcc-c++ \
  git openssl-devel glib-devel glib2-devel gtk3-devel \
  pcsc-lite-devel pcsc-lite pcsc-perl alsa-lib-devel libXrender-devel \
  libXrandr-devel libX11-devel xorg-x11-proto-devel PackageKit-glib-devel json-glib-devel

Node.js

sudo dnf install nodejs nodejs-devel npm node-gyp nodejs-docs nodejs-debug

Pre Fedora 22:

sudo yum install nodejs nodejs-devel npm node-gyp nodejs-docs nodejs-debug

Other Dependencies

  1. Google Chrome
    1. Download the browser from https://www.google.com/chrome/index.html. When you choose the rpm version using Firefox, the browser will offer the option to install the package immediately.

RFID User Listener

In your GPII code directory:

# Clone the GPII PCSC Tools Repository
git clone https://github.com/GPII/linux-rfid-user-listener
cd linux-rfid-user-listener

# Compile and install
make all
sudo make install

# Start PCSC the daemon
sudo /usr/sbin/pcscd

# Run the scanner
./pcsc_scan

We also include a utility for reading and writing the tokens on smart cards.

# If you haven't started the daemon already do so.
sudo /usr/sbin/pcscd 

# Shows the model of tag you're using
python pcscutil.py get model

# Shows the current token stored on the card
python pcscutil.py get gpiitoken

# Sets the card token to 'nisha'
python pcscutil.py set gpiitoken nisha


Building and Starting the GPII Personalization Framework on Linux

First, clone the GPII Linux repository.

git clone git://github.com/GPII/linux.git
cd linux

We use the grunt task system to perform our build operations. If you don't have grunt installed yet you can do so with:

sudo npm install -g grunt-cli

To fetch our core universal dependencies and build the linux specific plugins run (note that the 'grunt build' below will install the GPII USB listener software for Linux/Fedora):

npm install
grunt build

Because the history of the universal repository is quite large, it can take a long time to clone (and sometimes will fail depending on the network). To check it out faster for testing use the fastClone option. Note however, you will need the regular build in order to commit code and push on universal.

grunt build --fastClone

To clean the plugin binaries use

grunt clean

Note that after the execution of the clean task the system won't work, so you have to skip this step if you're installing the GPII.

You can start the GPII local server on port 8080 using:

node gpii.js

To install and uninstall the listener components use the following. Note that this may prompt you for sudo access.

grunt install
grunt uninstall

To run the GPII USB listener, execute the command:

$ gpii-usb-user-listener

You may see an error when you run the above, namely: "ImportError: No module named httplib2". If so, execute the following command to install the httplib2 library, and then execute sudo gpii-usb-user-listener again:

$ sudo dnf install python-httplib2 python3-httplib2

Pre Fedora 22:

$ sudo yum install python-httplib2 python3-httplib2

Fedora In VirtualBox

Most of the GPII development team run Fedora Linux as a virtual machine with VirtualBox.

  1. Ensure you're running VirtualBox 4.1.10 or higher (https://www.virtualbox.org/)
  2. Set up a new Virtual Box VM
    1. Choose "Enable 3D Acceleration" in the Display tab
    2. Ensure you allocate sufficient disk space and RAM to support a full Fedora installation with GNOME Shell 3
  3. Update your kernel by running, as root: yum -y update kernel
  4. Restart your virtual machine
  5. Mount the VirtualBox Guest Additions disk by choosing Devices > Install Guest Additions from the VirtualBox menu bar
  6. As root:
    1. cd /run/meda/<username>/VBOXADD...
    2. sh ./VBoxLinuxAdditions.run
    3. restorecon -R -v /opt
  7. Restart your virtual machine

Windows Installation Instructions

Dependencies

  • Git
    • Install GitHub for Windows - it includes the command line Msysgit which you run as "Git Shell".
    • Or, for advanced developers, use Cygwin for a full Unix-like environment on Windows - note that this will expose you to many annoyances and oddities with, for example, file permissions, or the use of git by npm
  • Node.js
    • Next you need to install Node.js. Go to http://nodejs.org/download/ and download the latest version of v4.4.xx LTS (this was tested with v4.4.7). You should install the version (32-bit or 64-bit) which matches the bitness of your operating system.
    • Troubleshooting:
      • Node does not always appear on the path (so will not run in command line) until you re-login or restart Windows.
      • Note: you can easily switch between different versions of Node.js using nvmw (Simple Node Manager for Windows).
  • Download and install Python (e.g. Python 2.7.x).
  • VisualStudio - all developers require this in order to build any native modules in the npm tree - in practice only the C/C++ tools are necessary unless you want to build user listeners in which case C# support is also required.

Other:

  • Windows 7 has a bug with high-contrast mode in the 64-bit version. If you're running this Windows version, you'll need to install the hotfix linked from this Microsoft support page (x64 only).
  • Note that Windows 7 is not currently a supported and maintained platform for the GPII on Windows. Our support primarily is for Windows 10, with lower level support for Windows 8.1 and Windows 8

Building and Starting the GPII Personalization Framework on Windows

  • Open up a git compatible command prompt (e.g. git shell)
  • Create a GPII directory
    • mkdir /c/gpii (or wherever you prefer)
    • cd /c/gpii
  • Clone the GPII Windows repository
    • git clone git://github.com/GPII/windows.git 
  • cd windows
  • Install dependencies of the framework
  • Make sure grunt is installed:
    • npm install grunt
    • npm install -g grunt-cli
  • Build:
    • grunt build
  • Start the GPII Framework by running the following command in the gpii\windows folder:
    • node gpii.js

Installing the USB and RFID listeners

Use the Windows installer (or build the binaries by following the installation instructions in <gpii>\windows\UsbUserListener\README.txt).

Additional Windows Configuration

  • The Magnifier may be set to change magnification in steps of 100% by default. In order to enable smaller steps, start the Magnifier, open the Options (the cogwheel icon) and change the slider to 25%.
  • The following is optional but useful if you want to report back on bugs:
    • Open a command line and right-click on the command line's window.
    • In the context menu that pops up, select the "Layout" tab.
    • In the layout tab, change the "Height" of the "Screen Buffer Size" to a much higher number, e.g. 900. Then click OK to confirm the change.
    • As a result of this, most of the DOS windows that pop up when you start GPII will "store" more logging lines. These logging lines can be copied and pasted into bug reports. For guidance on how to copy those logging lines, see Microsoft's article To copy text from a command prompt window.

Troubleshooting

test without usb

Once you start the system (by using the node gpii.js command), you can test it without USB by navigating your browser to the following URLs:

With a version updated after 2015-10-09 you can also use:

get a list of currently logged in tokens

You can get a list of currently logged in tokens using the following URL:

Note: When you use localhost:8081 to log in tokens, you need to use the same host to get the list of tokens. When you use 127.0.0.1:8081 to log in tokens, you need to use http://127.0.0.1:8081/userToken.

run acceptance tests

You should also run the automated tests, especially before and after commits. To run the automated tests, go to the directory universal and run the following command:

  • node tests\all-tests.js

The output in the terminal should end with a line that says something like jq:  All tests concluded: 58/58 total tests passed in 6798 ms - PASS.


build.cmd vs grunt build

Windows build (build.cmd) errors

Note: build.cmd was replaced by grunt build in the Summer of 2014.

The Windows build script (build.cmd) sometimes causes errors. If this happens, you need to delete the folder npm-cache which is located in C:\Users\[USER]\AppData\Roaming (aka %APPDATA%).

You should also avoid renaming this folder by extending its name to e.g. npm-cache-old because this would still cause build errors. This build issue may occur when you install the GPII framework on a Windows computer where an older version of GPII was installed in the past.

Unsupported Configurations

Ubuntu 12.04 LTS Installation Instructions

Required packages

Use 'sudo apt-get install' to install the following packages:

sudo apt-get install git g++ curl libglib2.0-dev libasound2-dev libxrender-dev libxrandr-dev pcscd

The version of Node.js distributed in the Ubuntu package repository is very out of date. Instead, use the Installing Node.js via package manager instructions on to the Node.js wiki or build from source.

sudo apt-get update
sudo apt-get install -y python-software-properties python g++ make
sudo add-apt-repository -y ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs

Or build it from source:

  wget http://nodejs.org/dist/v0.10.23/node-v0.10.23.tar.gz
  tar -xvzf node-v0.10.23.tar.gz
  cd node-v0.10.23
  ./configure
  make
  sudo make install

Install node-gyp:

  sudo npm install -g node-gyp 

Other packages may be required. This will become clear when you run the build.sh bash file (see Building and Starting the GPII Personalization Framework on Linux).

Other Dependencies

  1. Google Chrome
 You can either:
Download the installer
OR
use 'sudo apt-get install google-chrome-stable'

RFID User Listener

Follow the steps described in the Fedora Installation Instructions

Mac Installation Instructions

Covering the installation of the universal package and node.js.

The Mac installation doesn't do much yet except running gpii in node.js. There are no settings handlers or listeners implemented yet, so only the http GET or POST requests will work.

  • Installing make: The make compiler is not automatically included in a Mac, but is included in the Xcode development package.
    • If you have already installed xcode, you can skip this step. Otherwise there are two possibilities as described below. Anyway you need an apple developer account, which is for free at this time.
    • Download and install Xcode from the apple developers page Apple Developer Center
    • or only install the "Command Line Tools For XCode" from Apple Developer Downloads
  • Install git. The GUI-Tools automatically install the command line tools too.
  • Install node.js in the terminal:
git clone git://github.com/ry/node.git
cd /node
./configure
make
sudo make install
  • Install GPII Universal

(to be tested.)

git clone git://github.com/GPII/universal.git

finally you need to mimic the structure in the git gpii linux version.

  • move the just downloaded "universal" directory to a place you like.
  • create a folder-structure looking like this
- gpii 
- mac
-- index.js
- node-modules
-- universal 
  • the index.js file needs to be created and for the beginning can contain
/*!
GPII Linux Personalization Framework Node.js Bootstrap

Copyright 2012 OCAD University

Licensed under the New BSD license. You may not use this file except in
compliance with this License.

You may obtain a copy of the License at
https://github.com/gpii/universal/LICENSE.txt
*/

var fluid = require("universal"),
    gpii = fluid.registerNamespace("gpii");

// fluid.require("gsettingsBridge", require); /* linux specific, like this you can load the handlers and listeners as soon as they are developed. */

gpii.config.makeConfigLoader({
    nodeEnv: gpii.config.getNodeEnv("fm.ps.sr.dr.mm.os.development"),
    configPath: gpii.config.getConfigPath() || "../node_modules/universal/gpii/configs"
});
  • the "universal" folder is the recently downloaded folder from github, containing all the downloaded files.
  • open the terminal and go to the just created index.js file. run:
node index.js

Well done, this will start the node.js server and make gpii running and listening. The Port number on which it is listening should be shown in the second-last output line, like this:

...
13:04:25.786:   Firing event registerMiddleware of component with typename gpii.requests and id 9c0m8p6e-14 to list of 1 listeners
13:04:25.787:   Firing event onHandlers of component with typename gpii.server and id 9c0m8p6e-9 to list of 1 listeners
13:04:25.789:   Server is running on port: 8081
13:04:25.789:   Cleared instantiators (last id 9c0m8p6e-8) from threadLocal for end of flowManager.preferencesServer.solutionsRegistry.deviceReporter.matchMaker.ontologyServer.development