GitLab steht wegen Wartungsarbeiten am Montag, den 10. Mai, zwischen 17:00 und 19:00 Uhr nicht zur Verfügung.

README.md 6.85 KB
Newer Older
1 2
# ARSnova

3 4 5
ARSnova is a modern approach to Audience Response Systems (ARS). It is released
under the GPLv3 license and is offered as a Software as a Service free of
charge. Head over to [arsnova.eu](https://arsnova.eu/) to see it in action.
6 7 8

![ARSnova](src/site/resources/showcase.png)

9 10 11 12 13
ARSnova consists of two projects: the mobile client and the backend. This
repository contains the mobile client code. You will find the backend at
[thm-projects/arsnova-backend](https://github.com/thm-projects/arsnova-backend).
If you plan to work on the client you have to build both repositories - the
backend and the client.
14

15
[![Build Status](https://travis-ci.org/thm-projects/arsnova-mobile.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-mobile)
16 17 18

## Getting Started

19 20 21 22 23 24
The most convenient way to get started developing ARSnova is by using our
[Vagrant](http://www.vagrantup.com/) environment, found at
[thm-projects/arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant).
Use your IDE on your host machine to make changes to ARSnova, while the build
process is completely handled by the Vagrant box. You will not need to install
any development tools.
25

26 27 28 29
[arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant) sets up a
virtual machine for both development and production use. The basic usage is
`vagrant up`, which will start the development environment. If you wish to start
production as well, use `vagrant up production`.
30

31 32
Once any machine has been started, all required ARSnova repositories are
automatically cloned from GitHub, so that you can start coding immediately.
33

34 35 36
To connect to your development machine, type `vagrant ssh`. After that, you can
start ARSnova inside the machine by running `./start.sh`. You can then access
ARSnova from your host machine by opening http://localhost:8080.
37

38
### QA Private Build
39

40 41 42 43 44 45 46
[arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant) also sets up
the build environment we use internally at THM, which consists of
[Jenkins](http://jenkins-ci.org/) and [SonarQube](http://www.sonarqube.org/).
The former provides a QA pipeline that builds, tests, analyzes, and finally
deploys ARSnova to the production environment. SonarQube is used for the
analyzation phase and provides a drill-down into many quality aspects, including
[technical debt](https://en.wikipedia.org/wiki/Technical_debt).
47

48 49
While the development environment is running, Jenkins and SonarQube are
available at:
50

51 52
- http://localhost:9000 (SonarQube)
- http://localhost:9090 (Jenkins)
53

54
### QA Public Build
55

56 57 58 59 60 61 62
We also leverage the cloud provided by [Travis CI](https://travis-ci.org/) and
[Sauce Labs](https://saucelabs.com/) to build and test ARSnova. Travis first
builds and unit tests the software, then it instructs Sauce Labs to run smoke
tests on different browsers and operating systems. This ensures that the basic
features of ARSnova work across browsers and platforms. See
[this example](https://saucelabs.com/tests/4beecf8c754f418da0b75259c039c077) to
get an idea.
63

64
Our official build status provided by Travis CI:
65

66 67 68 69
- [![Build Status](https://travis-ci.org/thm-projects/arsnova-backend.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-backend)
  for ARSnova Backend
- [![Build Status](https://travis-ci.org/thm-projects/arsnova-mobile.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-mobile)
  for ARSnova Mobile
70

71
## Development
72

73 74 75 76
This is the mobile client repository. The following chapters will guide you
through the installation, as well as the utilization of all requirements you
need to build and use the mobile client of ARSnova. Before you start, please
ensure that the server part has been arranged completely.
77

78
### Requirements
79

80
The mobile client uses Sencha Touch 2 as application framework. In order to work
81 82
with the client you have to install Sencha Cmd 4 (version 5 is currently not
compatible with ARSnova). The basic requirement for installing and using Sencha
83 84 85 86
Cmd is the presence of Ruby and Java Runtime Environment 1.7 (or newer).
Additionally, you need [Grunt](http://gruntjs.com/) to build the frontend which
runs on top of NodeJS. Before you continue, please ensure that all requirements
are installed properly.
87

88 89
The download links to the referred requirements, as well as the installation
guide for Sencha Cmd can be found here:
90

91
- [Download Sencha Cmd](http://www.sencha.com/products/sencha-cmd/)
92 93
- [Sencha Cmd documentation](http://docs.sencha.com/cmd/5.x/intro_to_cmd.html)
  (see subsection "System Setup")
94

95
### Building
96

97 98
ARSnova consists of two main projects: ARSnova Mobile (this repository) and
ARSnova Backend. You have to build both projects separately, in order to work
Daniel Gerhardt's avatar
Daniel Gerhardt committed
99
with the mobile client. If you need information regarding the installation of
100 101
ARSnova Backend, please look up the read me at
[thm-projects/arsnova-backend](https://github.com/thm-projects/arsnova-backend).
102

103 104
ARSnova Mobile is built by the Grunt task runner. When building the frontend for
the first time, you need to install the build dependencies via NPM:
105

106 107 108 109 110 111 112 113
	npm install -g grunt-cli
	cd /path/to/arsnova-mobile
	npm install

Afterwards, you can create a web archive for a servlet container by running:

	grunt package

114 115 116 117
This creates the archive `arsnova-mobile.war` in the `target` directory. If you
just wish to build the production system without creating an archive, you can use

	grunt build
118

119
#### Continuous Build
120

121
The commands above build the software in such a way that it can be put into
122
production immediately. However, this is not the best way to develop a feature
123
or to fix a bug. Instead, we provide several build commands, based on Sencha Cmd.
124

125
In order to develop and test on your local machine, you first need to run
126
the ARSnova backend. You can use Jetty to start it:
127

Daniel Gerhardt's avatar
Daniel Gerhardt committed
128
	cd /path/to/arsnova-backend
129 130
	mvn jetty:run

131 132
Then, and before you call any build command, you have to refresh your Sencha Cmd project.
To do so, open a second terminal and execute the following command:
133 134

	cd /path/to/arsnova-mobile
135 136 137 138
	grunt refresh

Next, we continously build ARSnova:

139
	grunt run
140

141
`grunt run` will automatically inform you about code issues detected by JSCS and
142 143
JSHint in files you modify. You can also run both code checkers via `grunt lint`,
or separately via `grunt jscs` and `grunt jshint`.
144

145
#### Build Environments
146

147 148 149 150
For `production`, all JavaScript and CSS files are minified and put into the
browser's cache. This is good to make your changes ready for production, but you
might want to have a faster build including proper stack traces while you are
still coding your feature. This is where the `testing` environment comes in.
151

152 153 154 155
By default, the `production` environment is used for `grunt build` while the
`testing` environment is used for `grunt run`. You can change this behavior by
appending `:<environment>` to the task name where `<environment>` can be one of
Sencha's environments or one of the shortcuts `prod` and `dev`.
156 157 158

## Credits

159 160
ARSnova is powered by Technische Hochschule Mittelhessen - University of Applied
Sciences.