Just want to take a peek at our code? You can browse it on the web here:

+

* http://git.eclipse.org/c/orion/

+

We also have GitHub mirrors if you prefer:

* https://github.com/eclipse/orion.client

* https://github.com/eclipse/orion.client

* https://github.com/eclipse/orion.server

* https://github.com/eclipse/orion.server

−

== Self hosting setup ==

+

== Getting the source onto your computer ==

−

We assume you are familiar with git. If not, review the [[Git | Eclipsepedia Git Page]]. You can use [http://www.eclipse.org/egit/ EGit] (the Eclipse Git client) or the command-line Git client. If you are on Windows, use msysgit if you prefer the command line git client.

Self-hosting involves running an Orion server on localhost, pointing your Orion editor at your local git repo directories, and working within Orion to make changes. Changes are committed using the command-line tools (or EGit), as a separate phase from the Orion workflow. Orion M6 will support an integrated Git workflow; see [[Orion/How Tos/Working with git | Working with git]].

+

=== Notes for Eclipse committers ===

+

This section applies only to [http://www.eclipse.org/membership/become_a_member/committer.php Eclipse Committers]. If you're not a committer, you can skip these instructions.

+

* Ensure that your Git configuration uses the same email address that you've set in your [https://dev.eclipse.org/portal/myfoundation/portal/portal.php Eclipse Foundation profile]. If the addresses don't match, you won't be able to push changes (see [[Git#Committers_new_to_Git]]).

+

* Committers need to use different URLs to access the Orion Git repositories. The URL includes your committer ID:

* '''For e4 committers:''' Ensure that your user name and email are set up properly so that your email matches the foundation's email address on record. Otherwise you can't push changes. See [[Git#Committers_new_to_Git]]

+

To edit Orion's own source code using Orion, there's two fundamentally different ways we can do it. Here are our options:

−

* Clone the Orion client and server repositories using the URLs below. Choose a target directory that works for you. You'll be importing this code later into Eclipse in order to run your changes on the local server.

+

; Pure cloud.

−

<br>For e4 committers:<br>

+

: Using a cloud deployment of Orion (like [http://orionhub.org/ OrionHub], a public Orion server that anyone can use), you checkout the Orion source code using Orion's built-in Git features, then edit and test it. There's no software install; all you need is a web browser. Since you don't control the server, this method only allows you to hack on the Orion client code. See [[Orion/Selfhosting|Selfhosting]] for instructions.<br><br>

: This method requires the Eclipse IDE and a build of Orion. On your local computer, you checkout the Orion source code, and launch the Orion server from your Eclipse IDE. You can develop both client-side and server-side code using this method. Git functionality can be provided by any Git client (Orion's built-in Git features, or [http://www.eclipse.org/egit/ EGit], or msysgit on Windows, or the native command-line Git client, etc). This method is more complex, but also more flexible.

Self-hosting locally involves running an Orion server on localhost, pointing your Orion editor at your local Git repo directories, and working within Orion to make changes. Changes are committed using any Git client; for instructions on Orion's Git features, see [[Orion/How Tos/Working with git | Working with git]].

−

Make sure that you have Git 1.7 or higher when using Git with http protocol.

* You can use any recent stable build of the Eclipse SDK to run the server. Many of us are using [http://download.eclipse.org/eclipse/downloads/drops/S-3.7M4-201012081300/index.php 3.7M4].

+

* You can use any recent stable build of the Eclipse SDK to run the server, such as [http://download.eclipse.org/eclipse/downloads/drops4/R-4.2.1-201209141800/ Eclipse 4.2.1].

−

=== Load The Source into Eclipse ===

+

* Optionally install the Eclipse Git tools via Help &gt; Install New Software. Select the '''Juno''' repository and search for 'Eclipse EGit' to find the package.

−

* [http://download.eclipse.org/e4/orion/ Download] a stable orion build (latest integration build is the current recommendation) and unpack it somewhere on your hard disk. This download will be used as a so-called "target platform" when you run the server from Eclipse.

+

+

=== Load the source into Eclipse ===

+

* [http://download.eclipse.org/orion/ Download] a stable orion build (latest integration build is the current recommendation) and unpack it somewhere on your hard disk. This download will be used as a so-called "target platform" when you run the server from Eclipse.

** Occasionally, new dependencies are introduced in the server and you will need to take a nightly build to keep up-to-date. Check the [https://dev.eclipse.org/mailman/listinfo/orion-dev orion-dev mailing list] if you aren't sure which build to take.

** Occasionally, new dependencies are introduced in the server and you will need to take a nightly build to keep up-to-date. Check the [https://dev.eclipse.org/mailman/listinfo/orion-dev orion-dev mailing list] if you aren't sure which build to take.

* Create a new workspace using your Eclipse SDK.

* Create a new workspace using your Eclipse SDK.

Line 52:

Line 63:

** Once you finish the wizard, you'll have a new target definition available in the list of targets.

** Once you finish the wizard, you'll have a new target definition available in the list of targets.

** Make this the active target definition for your self-hosting workspace.<br>[[Image:orion-targetdefinition.png]]

** Make this the active target definition for your self-hosting workspace.<br>[[Image:orion-targetdefinition.png]]

−

* Your workspace will be rebuilt and compile errors should disappear. There might be a few errors related to unsatisfied dependencies from test plugins, but you can ignore them for now.

+

* Your workspace will be rebuilt and most of the compile errors should disappear.

+

** There might be a few errors related to unsatisfied dependencies from <code>.tests</code> plugins, but you can ignore them for now. You can also ignore any errors from <code>org.eclipse.orion.server.ui</code>, as it is not required to launch the server. Right-click these projects and close them if you get sick of seeing the errors.

=== Set up the launch to run from source ===

=== Set up the launch to run from source ===

−

The plugin source you've loaded into Eclipse can now overwrite the plugins in the working stable build.

+

The plugin source you've loaded into Eclipse will now be used to run Orion, taking priority over the plugins in the working stable build.

* In the '''Arguments''' tab, set the VM argument that controls which directories the Orion server can access on your machine. You want to ensure the Orion server can update the files in your local git repo. Use whatever path format makes sense on your platform. Whatever format you use must match exactly what you type later into the "Link folder" dialog in Orion. (So if you use drive letters and back slashes on windows, you'll need to use the same format in the web client.)<br><pre>-Dorg.eclipse.orion.server.core.allowedPathPrefixes=c:\myLocalGitRepos</pre>

+

* The launch configuration we will use is associated with a [[Orion/Server_admin_guide|Orion server configuration file]] called '''web-ide.conf'''. This file controls which directories the Orion server can access on your machine, among other things. Since we want to use Orion to edit its own source code, we have to ensure the Orion server can access the files in your local git repo.

+

** Add a line like this to web-ide.conf: <br><pre>orion.file.allowedPaths=C:\\Users\\orionfan\\code\\orion</pre>The path points to the folder where you checked out the Orion source code. (Windows paths must be separated with '''double backslashes'''!)

+

* On the '''Bundles''' tab, ensure that "Launch with: '''features selected below'''" is selected. Ensure there are five Orion features checked (see image below)

+

[[Image:Orion-launch-config.png]]

* If you only want to work on the client (not the server), you can now close the server projects (5 client projects should remain).

* If you only want to work on the client (not the server), you can now close the server projects (5 client projects should remain).

−

* On "Bundles" pick "Select All". (I don't know why)

+

−

=== Running the Server ===

+

=== Run the server ===

−

* Run the launch and point your browser at [http://localhost:8080 http://localhost:8080]

+

* Run the launch configuration (click the '''Run''' button from the launch configuration dialog, or use the '''Run''' command on the Eclipse toolbar.)

* Once logged in, you'll see your navigator with some auto-generated content (folders called "org.core.orion.client.*"). You can ignore this content and delete the folders.

+

* Once logged in, you'll see an empty Navigator view. Click the '''New''' button and choose '''Link to Server'''.

−

* Click the Link Folder button on the toolbar and add a folder that links to your local git repos. For example, if you wanted to make changes to the client, you could link a folder named "org.eclipse.orion.client.core" to the following file path:<br><pre>c:\myLocalGitRepos\org.eclipse.orion.client\bundles\org.eclipse.orion.client.core</pre>

+

* Type a name (for example, "Orion Client") and in the '''Server Path''' field, enter the path to the Orion code on your local machine.

−

* Repeat the previous step to add links for each bundle in the git repository that you care about.

+

** The path must be of one of the <code>orion.file.allowedPaths</code> entries we created in the previous section (or a subfolder thereof).

+

** For example, if you wanted to make changes to the client, you might link to the following file path:<br><pre>C:\Users\orionfan\code\orion\org.eclipse.orion.client</pre>

+

<!--* Repeat the previous step to add links for each git repository that you care about.-->

* You should see the folders show up in your Orion explorer:<br>[[Image:orion-navexampleM6.png]]

* You should see the folders show up in your Orion explorer:<br>[[Image:orion-navexampleM6.png]]

* From here, you can start editing files. As you make changes to the client code, you can simply reload the corresponding page in your browser to see the changes. We recommend you keep a browser tab open with a stable editor and stable navigator, and open a new tab for reloading and trying changes. In this way, you'll always have a couple of safe browser tabs to use to revert changes if you break something!

* From here, you can start editing files. As you make changes to the client code, you can simply reload the corresponding page in your browser to see the changes. We recommend you keep a browser tab open with a stable editor and stable navigator, and open a new tab for reloading and trying changes. In this way, you'll always have a couple of safe browser tabs to use to revert changes if you break something!

+

== Node.js on local computer ==

+

+

=== Installing from source ===

+

#Make sure you have Node.js and npm installed. See [http://nodejs.org/download/ nodejs.org] for details.

+

#[[Orion/Getting_the_source#Getting_the_source_onto_your_computer|Get the Orion source]]. You only need to get the [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git client source].

+

#Open a command shell and change directory to '''org.eclipse.orion.client/modules/orionode'''.

#*If you're not interested in developing the server, you can instead run <code>npm install --production</code>, which omits the dev-time dependencies for a smaller download.

+

+

=== Concatenation and Minification ===

+

By default the pages served up by Orionode are not concatenated or minified, so they will load rather slowly. You can mitigate this by running the client-side build. To do this, just run <code>build.js</code>, found in the <code>org.eclipse.orion.client/modules/orionode/build</code> directory:

+

node ./build/build.js

+

{{warning| Running the script will overwrite files in your working directory! Make sure anything important is committed to a branch first.}}

+

+

Clear your browser cache. The next time you load Orionode, it should be much faster.

+

+

=== Running tests ===

+

+

The Orion node server has its own test suite. See [[Orion/Running_the_tests#Node.js_Server_Tests]] for more details.

+

+

== Related links ==

+

+

See the [[Orion/Releng_Builds|Releng Builds]] page for details on how to contribute changes to the Orion build.

+

+

See the cloud [[Orion/Selfhosting|Selfhosting]] page for details on self-hosting purely from the browser

[[Category:Orion|Getting the source]]

[[Category:Orion|Getting the source]]

Revision as of 14:18, 8 February 2013

This page covers how to get the Orion source code, as well as how to set up for self-hosting (changing Orion code from Orion) using an Eclipse development environment.

Overview of self-hosting

To edit Orion's own source code using Orion, there's two fundamentally different ways we can do it. Here are our options:

Pure cloud.

Using a cloud deployment of Orion (like OrionHub, a public Orion server that anyone can use), you checkout the Orion source code using Orion's built-in Git features, then edit and test it. There's no software install; all you need is a web browser. Since you don't control the server, this method only allows you to hack on the Orion client code. See Selfhosting for instructions.

Local computer using Eclipse IDE.

This method requires the Eclipse IDE and a build of Orion. On your local computer, you checkout the Orion source code, and launch the Orion server from your Eclipse IDE. You can develop both client-side and server-side code using this method. Git functionality can be provided by any Git client (Orion's built-in Git features, or EGit, or msysgit on Windows, or the native command-line Git client, etc). This method is more complex, but also more flexible.

Local computer using Node.js

This method use Node.js to run a local Orion server, with Orion development tools running in the browser.

Local computer with Eclipse IDE

Self-hosting locally involves running an Orion server on localhost, pointing your Orion editor at your local Git repo directories, and working within Orion to make changes. Changes are committed using any Git client; for instructions on Orion's Git features, see Working with git.

Here are the steps needed to get up and running.

Install the Eclipse SDK

You can use any recent stable build of the Eclipse SDK to run the server, such as Eclipse 4.2.1.

Optionally install the Eclipse Git tools via Help > Install New Software. Select the Juno repository and search for 'Eclipse EGit' to find the package.

Load the source into Eclipse

Download a stable orion build (latest integration build is the current recommendation) and unpack it somewhere on your hard disk. This download will be used as a so-called "target platform" when you run the server from Eclipse.

Occasionally, new dependencies are introduced in the server and you will need to take a nightly build to keep up-to-date. Check the orion-dev mailing list if you aren't sure which build to take.

Create a new workspace using your Eclipse SDK.

Use the File->Import->General->Existing Projects into Workspace wizard. In the wizard, set the root directory for the import to whatever directory you used when you cloned the Git repositories. You'll know you have the right path when you see a bunch of org.eclipse.orion.* projects in the project list.

Ensure that Copy projects into workspace is not checked. Feel free to import just a subset of the projects (for example, just client plugins) - the remaining ones will come from the 'target platform'.

The projects should appear in your workspace. Don't worry about compile errors just yet until after you've set up the target platform.

Now you need to set up a target that points to the Orion build you downloaded. (Window->Preferences->Plug-in Development->Target Platform).

Once you finish the wizard, you'll have a new target definition available in the list of targets.

Make this the active target definition for your self-hosting workspace.

Your workspace will be rebuilt and most of the compile errors should disappear.

There might be a few errors related to unsatisfied dependencies from .tests plugins, but you can ignore them for now. You can also ignore any errors from org.eclipse.orion.server.ui, as it is not required to launch the server. Right-click these projects and close them if you get sick of seeing the errors.

Set up the launch to run from source

The plugin source you've loaded into Eclipse will now be used to run Orion, taking priority over the plugins in the working stable build.

Open the Run->Run Configurations dialog, expand OSGi Framework, and select the OSGi Framework launch called web-ide.

The launch configuration we will use is associated with a Orion server configuration file called web-ide.conf. This file controls which directories the Orion server can access on your machine, among other things. Since we want to use Orion to edit its own source code, we have to ensure the Orion server can access the files in your local git repo.

Add a line like this to web-ide.conf:

orion.file.allowedPaths=C:\\Users\\orionfan\\code\\orion

The path points to the folder where you checked out the Orion source code. (Windows paths must be separated with double backslashes!)

On the Bundles tab, ensure that "Launch with: features selected below" is selected. Ensure there are five Orion features checked (see image below)

If you only want to work on the client (not the server), you can now close the server projects (5 client projects should remain).

Run the server

Run the launch configuration (click the Run button from the launch configuration dialog, or use the Run command on the Eclipse toolbar.)

Once logged in, you'll see an empty Navigator view. Click the New button and choose Link to Server.

Type a name (for example, "Orion Client") and in the Server Path field, enter the path to the Orion code on your local machine.

The path must be of one of the orion.file.allowedPaths entries we created in the previous section (or a subfolder thereof).

For example, if you wanted to make changes to the client, you might link to the following file path:

C:\Users\orionfan\code\orion\org.eclipse.orion.client

You should see the folders show up in your Orion explorer:

From here, you can start editing files. As you make changes to the client code, you can simply reload the corresponding page in your browser to see the changes. We recommend you keep a browser tab open with a stable editor and stable navigator, and open a new tab for reloading and trying changes. In this way, you'll always have a couple of safe browser tabs to use to revert changes if you break something!

Node.js on local computer

Installing from source

Make sure you have Node.js and npm installed. See nodejs.org for details.

Open a command shell and change directory to org.eclipse.orion.client/modules/orionode.

Run the npm install command to automatically download Orionode's dependencies.

If you're not interested in developing the server, you can instead run npm install --production, which omits the dev-time dependencies for a smaller download.

Concatenation and Minification

By default the pages served up by Orionode are not concatenated or minified, so they will load rather slowly. You can mitigate this by running the client-side build. To do this, just run build.js, found in the org.eclipse.orion.client/modules/orionode/build directory:

node ./build/build.js

Running the script will overwrite files in your working directory! Make sure anything important is committed to a branch first.

Clear your browser cache. The next time you load Orionode, it should be much faster.