rhoconnect 3.4.5 → 4.0.0.beta.10

data/doc/install.txt

@@ -4,141 +4,91 @@ This section discusses how to install the development environment for RhoConnect
 
 ## Installing RhoConnect with RhoStudio
 
-The most common way to install RhoConnect on a Windows or Macintosh platform is to install RhoMobile Suite. The RhoMobile Suite installer installs Rho products, such as Rhodes, RhoConnect, RhoElements, and RhoStudio. RhoStudio is an Eclipse installation that facilitates development of native smartphone applications.
+To install RhoConnect on a Windows or Macintosh platform, install RhoMobile Suite. The RhoMobile Suite installer installs Rho products, such as Rhodes, RhoConnect, RhoElements, and RhoStudio. RhoStudio is an Eclipse installation that facilitates development of native smartphone applications.
 
 [Click here for the RhoMobile Suite installation instructions](/rhomobile-install).
 
-NOTE: The rest of this chapter consists of instructions for installing RhoConnect from the command line, without using the RhoMobile Suite installer. You do not need to perform those instructions if you installed using the RhoMobile Suite installer.
-
-## Installing RhoConnect from the Command Line
+When you start RhoStudio, you set the location of the workspace directory. Set this path to a workspace directory that does not contain space symbols: if the path has spaces, a RhoConnect application created with RhoStudio will not work properly.
 
-To install RhoConnect on Linux, and to install RhoConnect on Windows or Mac OS using the command line (this does not install RhoStudio), you need to install the Rhodes gem. Download and install:
-
-1. [Ruby v1.9.3](http://www.ruby-lang.org/en/downloads/).
+NOTE: The rest of this chapter consists of instructions for installing RhoConnect from the command line, without using the RhoMobile Suite installer. You do not need to perform those instructions if you installed using the RhoMobile Suite installer.
 
-	* On Windows, [RubyInstaller](http://rubyinstaller.org) is a convenient way to install Ruby; you should check "Add Ruby executables to your PATH" and "Associate .rb and .rbw files with this Ruby installation".
+## Installing Ruby on Linux and Mac OSX
 
-	* On Macintosh, Ruby is already installed, but this version is outdated and isn't compatible with RhoStudio: install [Ruby Version Manager](https://rvm.io//) (RVM) and then use RVM to install Ruby version 1.9.3.
+Mac OS X comes with Ruby already pre-installed, but it’s an older version (1.8.7) which not supported by RhoConnect.
+Every Linux distribution usually has Ruby packages and you should refer to your distribution's documentation and community forums for help installing it.
+But, usually, these packages are behind and don't include latest Ruby versions.
 
-2. Ruby Web Server - We tested with [thin](http://code.macournoyer.com/thin/), and [passenger](http://www.modrails.com/). WEBrick, the web server that ships with ruby, is known to cause issues with HTTP headers/cookies and is ***not*** recommended.
+In nutshell, to have latest Ruby version you either need build it from sources, or use one of Ruby installers:
 
-3. [Redis](http://redis.io/) - RhoConnect includes a simple [rhoconnect task](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32) `rhoconnect redis-install` to install redis, covered in the [Rhoconnect CLI section](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32). Alternatively, you can [install redis directly](http://redis.io/download).
+1. Use [Ruby Version Manager](https://rvm.io) (RVM). RVM starting from v1.19 includes new `autolibs` feature and allow you to automatically install all dependencies on your system. RVM with `autolibs` enabled works with the system package manager. But in the case for OSX
+there's no a default package manager, and you have to select what package manager will be installed with autolibs modes `osx_brew` (default), `osx_port`, `osx_fink` and `smf`.
 
-4. Install the RhoConnect Gem.
+2. Manually download and install [Ruby v1.9.3](http://www.ruby-lang.org/en/downloads/).  Your mileage may vary depending on your machine, since you will need to resolve all build and install dependencies on your own.
 
-Run this command to install the RhoConnect Gem.
+Type this command to install stable RVM release:
 
 	:::term
-	$ gem install rhoconnect
-
-NOTE: If you get any `no such file to load -- something` messages while running the rhoconnect or rhodes commands, this can usually be resolved by putting "sudo" in front of the command, as in `sudo gem install something`.
-
-NOTE: Windows doesn't come with the necessary build tools to install gems ('make', for example). There are various ways to get these tools, but the GnuWin32 project at http://gnuwin32.sourceforge.net/ provides the tools, and can be conveniently installed via the GetGnuWin32 installer at http://sourceforge.net/projects/getgnuwin32/files/. You should follow the GetGnuWin32 instructions carefully.
-
-## Setting the Location of the RhoStudio Workspace Directory
-
-When you start RhoStudio, you can set the location of the workspace directory. The path to the workspace directory should not contain space symbols: if the path has spaces, a RhoConnect application created with RhoStudio will not work properly.
-
-## Standalone Ruby Installation and Ruby Version Manager
-
-Do not install Ruby as a standalone if you also use Ruby Version Manager (rvm) to install Ruby. If you need only one version of Ruby, you can install Ruby as a standalone. If you need more than one version of Ruby, you should uninstall standalone Ruby and then install Ruby with Ruby Version Manager. Mixed standalone Ruby and rvm-controlled Ruby installations can conflict and cause runtime issues in Rhodes applications.
-
-## Migrating to OS X Mountain Lion from the command line
-
-If you had a workable RhoConnect environment on Macintosh OS X Lion, then after you upgrade to Mountain Lion, you need to do some extra steps to restore your workable environment.
-
-### Getting Xcode and Command Line Tools Installed
-
-You can get Xcode from the Mac App Store. You’ll need at least version 4.4 of Xcode for it to work with OS X Mountain Lion. After the installation, open Xcode in your /Applications folder. Then go to Xcode -> Preferences -> Downloads tab and install the “Command Line Tools.”
+	$ curl -L https://get.rvm.io | bash -s stable
 
-### Installing Homebrew and GCC
-
-If you need to install any Ruby that’s older than 1.9.3, such as 1.9.2, 1.8.7 or REE, you’ll need to install GCC 4.2. Apple does not ship the Command Line Tools with gcc-4.2 compiler anymore (you can check by running `which gcc-4.2`), so you need to install it via Homebrew by enabling [homebrew-dupes](https://github.com/Homebrew/homebrew-dupes) repository and installing GCC.
+If you want get the libraries installed automatically, then use autolibs mode 4 a.k.a. enable.
 
 	:::term
-	$ brew tap homebrew/dupes
-	$ brew install apple-gcc42
-
-Apple has removed X11 support from their operating system, but the X11 package is needed to
-compile 1.8.7 or REE. You can get the X11 package from [XQuartz]( http://xquartz.macosforge.org/landing). By default, it installs in the /opt/X11 folder.
-
-If you had Homebrew already installed, then you need only update it
+	$ rvm autolibs 4
 
+On Mac OSX you can also optionally enforce a package manager of your choice:
+ 
 	:::term
-	$ brew update
-	$ brew doctor
-
-If the `brew doctor` command complains about the `/usr/local/bin` path, then edit the `/etc/paths` file to move `/usr/local/bin` line to the top of it.
+	$ rvm autolibs homebrew
 
-### Updating RVM (Ruby Version Manager) with Ruby 1.9.3
-
-Because the OS X Mountain Lion toolchain is changed, you should use Ruby Version Manager to reinstall existing Ruby 1.9.3.
+And, finally, install desired Ruby version:
 
 	:::term
-	$ rvm get stable
-	$ rvm reinstall 1.9.3
+	$ rvm install 1.9.3
+	$ rvm install jruby
+	# rvm install 2.0.0
 
-### Installing legacy rubies
+**NOTE: The full list of `autolibs` options is covered in the [RVM docs](https://rvm.io/rvm/autolibs/).**
 
-Run the following commands to install legacy rubies:
+**NOTE: On Mac OSX to need to have `Xcode` and `Command Line Tools` installed.**
 
-	:::term
-	$ export CPPFLAGS=-I/opt/X11/include
-	$ CC=/usr/local/bin/gcc-4.2 rvm reinstall 1.8.7
-	$ CC=/usr/local/bin/gcc-4.2 rvm reinstall ree
 
-## Upgrading an Existing Application
+## Installing RhoConnect on Linux
 
-If you have an existing application, upgrading to the latest version of RhoConnect is simple.
+On Linux, you need the following setup before redis is installed.
 
-Open the `Gemfile` of your application and find the rhoconnect line, it should look something like:
+ * The `/usr/local` directory exists and is recursively writable by the current user.
+ * The `/usr/local/etc/` directory exists and is recursively writable by the current user.
+ * You need a gcc toolchain installed, i.e. via build-essential package on Ubuntu/Debian.
 
-	:::ruby
-	gem 'rhoconnect', '3.3.6'
+To install RhoConnect on Linux, you need to install the RhoConnect gem. Download and install:
 
-Change this to the latest release version, which you can find on [rubygems.org](http://rubygems.org/gems/rhoconnect), for example if it is 3.4.0:
 
-	:::ruby
-	gem 'rhoconnect', '3.4.0'
+1. Ruby Web Server - We tested with [thin](http://code.macournoyer.com/thin/), and [passenger](http://www.modrails.com/). WEBrick, the web server that ships with ruby, is known to cause issues with HTTP headers/cookies and is ***not*** recommended.
 
-Run the following command from the root application directory:
+2. [Redis](http://redis.io/) - RhoConnect includes a simple [rhoconnect task](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32) `rhoconnect redis-install` to install redis, covered in the [Rhoconnect CLI section](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32). Alternatively, you can [install redis directly](http://redis.io/download).
 
-	:::term
-	$ bundle install
+3. Install the RhoConnect Gem.
 
-Now update your application's RhoConnect dependency manifest:
+Run this command to install the RhoConnect Gem.
 
 	:::term
-	$ rhoconnect update
+	$ gem install rhoconnect
 
-## Upgrading previous versions to RhoConnect 3.4+
+**NOTE: Do not install Ruby as a standalone if you also use Ruby Version Manager (rvm) to install Ruby. If you need only one version of Ruby, you can install Ruby as a standalone. If you need more than one version of Ruby, you should uninstall standalone Ruby and then install Ruby with Ruby Version Manager. Mixed standalone Ruby and rvm-controlled Ruby installations can conflict and cause runtime issues in RhoConnect applications.**
 
-If you have an existing RhoConnect application using version < 3.4 and want to upgrade it to RhoConnect 3.4+, then
-you need to update the `Gemfile` file to properly use the latest RhoConnect runtime dependencies.
+## Setting the HTTP_PROXY Environment Variable
 
-First, follow the instructions described in the [previous section](/rhoconnect/install#upgrading-an-existing-application).
+If you are using RestClient, you should set the HTTP_PROXY environment variable to your proxy server URL. This allows the bundler to work from behind a proxy.
 
-Next, make sure your `Gemfile` looks like the following example, replacing the version as necessary.
-The `rhoconnect update` command will generate a reference `Gemfile.new` which you can use to replace your `Gemfile`:
+From Linux or OSX, you can use the following command.
 
-	:::ruby
-	source 'http://rubygems.org'
+	$ export http_proxy=http://{username}:{password}@{proxy-server-name}
 
-	gem 'rhoconnect', '<put correct version here>'
-	gemfile_path = File.join(File.dirname(__FILE__), ".rcgemfile")
+From Windows:
 
-	begin
-		eval(IO.read(gemfile_path))
-	rescue Exception => e
-		puts "ERROR: Couldn't read RhoConnect .rcgemfile"
-		puts e.message
-		exit 1
-	end
+	$ SET HTTP_PROXY=http://{username}:{password}@{proxy-server-name}
 
-	# DON'T FORGET to add your application specific gems after this line ...
-	# ...
+This allows you to set the RestClient proxy using the HTTP_PROXY environment variable in your RhoConnect code.
 
-Finally, run `bundle install` to install any missing dependencies:
-
-	:::term
-	$ bundle install
+	:::ruby
+	RestClient.proxy = ENV['http_proxy']

data/doc/introduction.txt

@@ -9,7 +9,7 @@ RhoConnect does not require use of Rhodes for the client app.  It can also be us
 
 RhoConnect consists of the following components:
 
-* Synchronization Framework - The core of RhoConnect, this facilitates data synchronization between the Rhodes / RhoConnect-Client and a 3rd party source (SOAP, REST, etc...). Each source is synchronized by implementing a simple "source adapter" class. The client connects with the embedded [sinatra](http://www.sinatrarb.com/) server to interact with the collection of source adapters.  RhoConnect uses [redis](http://redis.io/) to efficiently cache data to be synchronized.
+* Synchronization Framework - The core of RhoConnect, this facilitates data synchronization between the Rhodes / RhoConnect-Client and a 3rd party source (SOAP, REST, etc...). Each source is synchronized by implementing a "source adapter" which consists of model and controller. The client connects with the embedded [sinatra](http://www.sinatrarb.com/) server to interact with the collection of source adapters.  RhoConnect uses [redis](http://redis.io/) to efficiently cache data to be synchronized.
 
 * REST API - RhoConnect exposes a simple REST API for interacting with an application.  See the [REST API docs](/rhoconnect/rest-api) for more information.