Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 159 lines (110 sloc) 7.519 kb
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
1 ## Welcome To Chromeless!
dab46a3 @lloyd splain thyself\!
lloyd authored
2
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
3 The 'chromeless' project is an experiment into making it possible to build
4 a web browser using only web technologies, like HTML, JavaScript, and CSS.
dab46a3 @lloyd splain thyself\!
lloyd authored
5
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
6 The project is based on [addon-sdk (aka,
105dd21 @lloyd minor readme tweaks
lloyd authored
7 "jetpack")](http://github.com/mozilla/addon-sdk), and
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
8 [xulrunner](https://developer.mozilla.org/en/xulrunner).
dab46a3 @lloyd splain thyself\!
lloyd authored
9
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
10 ## Current State
dab46a3 @lloyd splain thyself\!
lloyd authored
11
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
12 This project is *highly* experimental, rapidly changing, and probably
105dd21 @lloyd minor readme tweaks
lloyd authored
13 insecure. As the project matures, this notice will change.
dab46a3 @lloyd splain thyself\!
lloyd authored
14
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
15 ## Design Overview
16
c20d96f @taboca Updates to align with new view which Chromeless, 0.2, gives more focus t...
taboca authored
17 Chromeless can be used to created desktop applications using HTML,
18 and related web technologies. In version 0.1, the original goal was a focus
19 towards authoring a browser-like applications in HTML. That is still valid, however,
20 now you can also use Chromeless to create all sorts of apps that can be executed like
21 a native application, but where all of the look and feel, and many of the
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
22 behaviors are defined by HTML, CSS, and javascript provided by the developer.
dab46a3 @lloyd splain thyself\!
lloyd authored
23
c20d96f @taboca Updates to align with new view which Chromeless, 0.2, gives more focus t...
taboca authored
24 This "main app HTML" is basically a normal webpage, but with several important differences:
dab46a3 @lloyd splain thyself\!
lloyd authored
25
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
26 * The HTML file has access to a 'window.require()' function that it can use to
27 access new APIs that give it increased priviledges.
5085ec1 Doc
Marcio Galli authored
28
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
29 * (untrusted) Web content can be rendered inside iframes which are children of the
c20d96f @taboca Updates to align with new view which Chromeless, 0.2, gives more focus t...
taboca authored
30 top level "main app HTML". This content cannot tell its rendered inside an iframe,
31 and has no special access to the main app context.
5085ec1 Doc
Marcio Galli authored
32
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
33 * Several new events and conventions are introduced. For instance, the title of the
34 top level browser HTML is the name of the running process (not yet implemented),
35 new, non-standard events are available to the top level browser HTML which give it
36 a priviledged view (and control) over embedded web content.
2cbedb6 @taboca How to build the output application to execution with xulrunner. We will...
taboca authored
37
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
38 ## Prerequisites
2cbedb6 @taboca How to build the output application to execution with xulrunner. We will...
taboca authored
39
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
40 * OSX 10.5 and later, Windows XP and later, or probably a modern versions of linux (32 or 64 bit).
41 * Python 2.5 - 2.7 (3 is not supported); Python 2.6 or 2.7 are recommended (testing isn't as thorough with 2.5).
8d7faed @taboca Simplified the `package` option. Simply removed the `application.ini` fr...
taboca authored
42
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
43 ## Getting Started
2cbedb6 @taboca How to build the output application to execution with xulrunner. We will...
taboca authored
44
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
45 The top level `chromeless` python script is capable of several things:
2cbedb6 @taboca How to build the output application to execution with xulrunner. We will...
taboca authored
46
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
47 * running a browser when provided a path to 'browser HTML'
48 * packaging a browser as a xulrunner package, or a standalone exectuable (not yet implemented)
49 * running unit tests (not yet implemented)
50 * generating static documentation for all current APIs (not yet implemented)
2cbedb6 @taboca How to build the output application to execution with xulrunner. We will...
taboca authored
51
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
52 To get started, you should clone this repository (or download a versioned snapshot) and run:
dab46a3 @lloyd splain thyself\!
lloyd authored
53
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
54 (win32) C:\xxx\chromeless> chromeless
55 (osx) $ ./chromeless
1e7601a @lloyd call out issues with ffx 4 betas and this hack
lloyd authored
56
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
57 By default, the HTML files in `examples/first_browser` will be executed, and you'll see a very
58 simple browser based on them. You may also specify an alternate browser HTML on the command line:
dab46a3 @lloyd splain thyself\!
lloyd authored
59
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
60 (win32) C:\xxx\chromeless> chromeless examples\webgl
61 (osx) $ ./chromeless examples/webgl
dab46a3 @lloyd splain thyself\!
lloyd authored
62
5e8f031 @lloyd rewrite README with updated status and information
lloyd authored
63 From here, you can inspect the implementation of any of these samples, copy, modify and explore.
dab46a3 @lloyd splain thyself\!
lloyd authored
64
0220083 @lloyd update README with new commands (appify and changed behavior of package)...
lloyd authored
65 For deployment or to share your application, you can use chromeless to generate a standalone
66 application folder, that anyone on a supported platform can run. Output will be placed
67 in the build/ directory:
dab46a3 @lloyd splain thyself\!
lloyd authored
68
0220083 @lloyd update README with new commands (appify and changed behavior of package)...
lloyd authored
69 (win32) C:\xxx\chromeless> chromeless appify examples\webgl
70 (osx) $ ./chromeless appify examples/webgl
dab46a3 @lloyd splain thyself\!
lloyd authored
71
0220083 @lloyd update README with new commands (appify and changed behavior of package)...
lloyd authored
72 Finally, it's possible to generate a "XULRunner application", which is a folder that is much
73 smaller than a standalone application, but can be run under (a specific version of) xulrunner.
74 Again, the output will be placed in the build/ directory:
cd4f8cb @taboca xulapp-install assumes one has used 'chromeless app package' mode and ha...
taboca authored
75
0220083 @lloyd update README with new commands (appify and changed behavior of package)...
lloyd authored
76 (win32) C:\xxx\chromeless> chromeless package examples\webgl
77 (osx) $ ./chromeless package examples/webgl
dab46a3 @lloyd splain thyself\!
lloyd authored
78
aad6054 @taboca How to generate local documentation
taboca authored
79 ## Documentation and Additional Information
dab46a3 @lloyd splain thyself\!
lloyd authored
80
aad6054 @taboca How to generate local documentation
taboca authored
81 To generate a local API documentation, use:
084b623 @lloyd add blanket tri-license
lloyd authored
82
aad6054 @taboca How to generate local documentation
taboca authored
83 (win32) C:\xxx\chromeless> chromeless docs
84 (osx) $ ./chromeless docs
85
985a2d5 @taboca Early gallery, tests, and fix to online docs link
taboca authored
86 You may also check the [Chromeless documentation online](http://mozilla.github.com/chromeless), plus
aad6054 @taboca How to generate local documentation
taboca authored
87 inline examples can also be helpful. You can always find us on irc in `#labs`
88 at `irc.mozilla.org`, or get help or discuss this project on our mailing
89 list: `mozilla-labs@googlegroups.com`
084b623 @lloyd add blanket tri-license
lloyd authored
90
985a2d5 @taboca Early gallery, tests, and fix to online docs link
taboca authored
91 ## Sub-projects for Tests
92
93 A Tests application is provided along wth Chromeless and can execute tests for all the
94 apps under tests/ directory that have the test-app.js file in it:
95
96 (win32) C:\xxx\chromeless> chromeless tests
97 (osx) $ ./chromeless tests
98
99 ## Gallery
100
101 An early version of a developer's gallery is now part of this git repository using
102 git sub-modules. You may use Chromeless to launch or package these examples that
bb40c05 @taboca Using the sub-modules in the gallery 0.1
taboca authored
103 provided in the gallery/ directory. In order to pull the projects from the gallery/
104 , you will need to initialize and update using git submodule. Example:
105
106 (linux) git submodule init ./gallery/simple-text-editor
107 (win32) git submodule init .\gallery\simple-text-editor
108
109 (linux) git submodule update ./gallery/simple-text-editor
110 (win32) git submodule update .\gallery\simple-text-editor
111
112 (win32) C:\xxx\chromeless> chromeless .\gallery\simple-text-editor
113 (osx) $ ./chromeless ./gallery/simple-text-editor
985a2d5 @taboca Early gallery, tests, and fix to online docs link
taboca authored
114
cc831a5 @taboca Known issues notes from the blog post
taboca authored
115 ## Notes and Known Issues
116
117 * You need to pass a relative path to your application when you invoke chromeless script
118 * This version only packages your files that are under your main application directory. So if you use, for example, jquery in a sub-directory, it will not be bundled. Make sure you have all your files in the same directory.
119 * With Mac OSX, if you launch the application for tests ( not passing package option ), the keyboard output will show in the console and not in the browser screen. For Mac OSX, you may need to use the "package" argument and install in your machine.
120 * It works with some specific versions of XULRunner. And to help out developers, the chromeless script will fetch a XULRunner SDK.
121
084b623 @lloyd add blanket tri-license
lloyd authored
122 ## LICENSE
123
124 All files that are part of this project are covered by the following
125 license, except where explicitly noted.
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
126
084b623 @lloyd add blanket tri-license
lloyd authored
127 Version: MPL 1.1/GPL 2.0/LGPL 2.1
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
128
129 The contents of this file are subject to the Mozilla Public License Version
130 1.1 (the "License"); you may not use this file except in compliance with
131 the License. You may obtain a copy of the License at
084b623 @lloyd add blanket tri-license
lloyd authored
132 http://www.mozilla.org/MPL/
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
133
084b623 @lloyd add blanket tri-license
lloyd authored
134 Software distributed under the License is distributed on an "AS IS" basis,
135 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
136 for the specific language governing rights and limitations under the
137 License.
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
138
084b623 @lloyd add blanket tri-license
lloyd authored
139 The Original Code is chromeless.
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
140
084b623 @lloyd add blanket tri-license
lloyd authored
141 The Initial Developer of the Original Code is the Mozilla Foundation.
142
143 Portions created by the Initial Developer are Copyright (C) 2010
144 the Initial Developer. All Rights Reserved.
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
145
084b623 @lloyd add blanket tri-license
lloyd authored
146 Contributor(s):
c48d2fc @ianb Really Python 2.5 isn't likely to work. And whitespace
ianb authored
147
084b623 @lloyd add blanket tri-license
lloyd authored
148 Alternatively, the contents of this file may be used under the terms of
149 either the GNU General Public License Version 2 or later (the "GPL"), or
150 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
151 in which case the provisions of the GPL or the LGPL are applicable instead
152 of those above. If you wish to allow use of your version of this file only
153 under the terms of either the GPL or the LGPL, and not to allow others to
154 use your version of this file under the terms of the MPL, indicate your
155 decision by deleting the provisions above and replace them with the notice
156 and other provisions required by the GPL or the LGPL. If you do not delete
157 the provisions above, a recipient may use your version of this file under
158 the terms of any one of the MPL, the GPL or the LGPL.
Something went wrong with that request. Please try again.