1 [jQuery](http://jquery.com/) - New Wave JavaScript
2 ==================================================
5 --------------------------------------
7 In the spirit of open source software development, jQuery always encourages community code contribution. To help you get started and before you jump into writing code, be sure to read these important contribution guidelines thoroughly:
9 1. [Getting Involved](http://docs.jquery.com/Getting_Involved)
10 2. [Core Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
11 3. [Tips For Bug Patching](http://docs.jquery.com/Tips_for_jQuery_Bug_Patching)
14 What you need to build your own jQuery
15 --------------------------------------
17 In order to build jQuery, you need to have GNU make 3.8 or later, Node.js/npm latest, and git 1.7 or later.
18 (Earlier versions might work OK, but are not tested.)
20 Windows users have two options:
22 1. Install [msysgit](https://code.google.com/p/msysgit/) (Full installer for official Git),
23 [GNU make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm), and a
24 [binary version of Node.js](http://node-js.prcn.co.cc/). Make sure all three packages are installed to the same
25 location (by default, this is C:\Program Files\Git).
26 2. Install [Cygwin](http://cygwin.com/) (make sure you install the git, make, and which packages), then either follow
27 the [Node.js build instructions](https://github.com/ry/node/wiki/Building-node.js-on-Cygwin-%28Windows%29) or install
28 the [binary version of Node.js](http://node-js.prcn.co.cc/).
30 Mac OS users should install Xcode (comes on your Mac OS install DVD, or downloadable from
31 [Apple's Xcode site](http://developer.apple.com/technologies/xcode.html)) and
32 [http://mxcl.github.com/homebrew/](Homebrew). Once Homebrew is installed, run `brew install git` to install git,
33 and `brew install node` to install Node.js.
35 Linux/BSD users should use their appropriate package managers to install make, git, and node, or build from source
36 if you swing that way. Easy-peasy.
39 How to build your own jQuery
40 ----------------------------
42 First, clone a copy of the main jQuery git repo by running:
45 git clone git://github.com/jquery/jquery.git
48 Enter the directory and install the node dependencies:
51 cd jquery && npm install
55 Make sure you have `grunt` installed by testing:
63 Then, to get a complete, minified (w/ Uglify.js), linted (w/ JSHint) version of jQuery, type the following:
70 The built version of jQuery will be put in the `dist/` subdirectory.
73 ### Modules (new in 1.8)
75 Starting in jQuery 1.8, special builds can now be created that optionally exclude or include any of the following modules:
84 To create a custom build, use the following special `grunt` commands:
98 Exclude **deprecated**:
101 grunt custom:-deprecated
104 Exclude **dimensions**:
107 grunt custom:-dimensions
113 grunt custom:-effects
122 Exclude **all** optional modules:
125 grunt custom:-ajax,-css,-dimensions,-effects,-offset
129 Note: dependencies will be handled internally, by the build process.
132 Running the Unit Tests
133 --------------------------------------
136 Start grunt to auto-build jQuery as you work:
139 cd jquery && grunt watch
143 Run the unit tests with a local server that supports PHP. No database is required. Pre-configured php local servers are available for Windows and Mac. Here are some options:
145 - Windows: [WAMP download](http://www.wampserver.com/en/)
146 - Mac: [MAMP download](http://www.mamp.info/en/index.html)
147 - Linux: [Setting up LAMP](https://www.linux.com/learn/tutorials/288158-easy-lamp-server-installation)
148 - [Mongoose (most platforms)](http://code.google.com/p/mongoose/)
153 Building to a different directory
154 ---------------------------------
156 If you want to build jQuery to a directory that is different from the default location:
159 grunt && grunt dist:/path/to/special/location/
161 With this example, the output files would be:
164 /path/to/special/location/jquery.js
165 /path/to/special/location/jquery.min.js
168 If you want to add a permanent copy destination, create a file in `dist/` called ".destination.json". Inside the file, paste and customize the following:
173 "/Absolute/path/to/other/destination": true
178 Additionally, both methods can be combined.
185 Update the submodules to what is probably the latest upstream code.
191 Note: This task will also be run any time the default `grunt` command is used.
198 As the source code is handled by the version control system Git, it's useful to know some features used.
202 The repository uses submodules, which normally are handled directly by the Makefile, but sometimes you want to
203 be able to work with them manually.
205 Following are the steps to manually get the submodules:
208 git clone https://github.com/jquery/jquery.git
216 git clone https://github.com/jquery/jquery.git
217 git submodule update --init
223 git clone --recursive https://github.com/jquery/jquery.git
226 If you want to work inside a submodule, it is possible, but first you need to checkout a branch:
233 After you've committed your changes to the submodule, you'll update the jquery project to point to the new commit,
234 but remember to push the submodule changes before pushing the new jquery commit:
238 git push origin master
247 If you want to purge your working directory back to the status of upstream, following commands can be used (remember everything you've worked on is gone after these):
250 git reset --hard upstream/master
256 For feature/topic branches, you should always used the `--rebase` flag to `git pull`, or if you are usually handling many temporary "to be in a github pull request" branches, run following to automate this:
259 git config branch.autosetuprebase local
261 (see `man git-config` for more information)
263 ### handling merge conflicts ###
265 If you're getting merge conflicts when merging, instead of editing the conflicted files manually, you can use the feature
266 `git mergetool`. Even though the default tool `xxdiff` looks awful/old, it's rather useful.
268 Following are some commands that can be used there:
270 * `Ctrl + Alt + M` - automerge as much as possible
271 * `b` - jump to next merge conflict
272 * `s` - change the order of the conflicted lines
273 * `u` - undo an merge
274 * `left mouse button` - mark a block to be the winner
275 * `middle mouse button` - mark a line to be the winner
279 [QUnit](http://docs.jquery.com/QUnit) Reference
285 expect( numAssertions );
291 note: QUnit's eventual addition of an argument to stop/start is ignored in this test suite so that start and stop can be passed as callbacks without worrying about their parameters
293 ### Test assertions ###
297 ok( value, [message] );
298 equal( actual, expected, [message] );
299 notEqual( actual, expected, [message] );
300 deepEqual( actual, expected, [message] );
301 notDeepEqual( actual, expected, [message] );
302 strictEqual( actual, expected, [message] );
303 notStrictEqual( actual, expected, [message] );
304 raises( block, [expected], [message] );
308 Test Suite Convenience Methods Reference (See [test/data/testinit.js](https://github.com/jquery/jquery/blob/master/test/data/testinit.js))
309 ------------------------------
311 ### Returns an array of elements with the given IDs ###
320 q("main", "foo", "bar");
322 => [ div#main, span#foo, input#bar ]
325 ### Asserts that a selection matches the given IDs ###
328 t( testName, selector, [ "array", "of", "ids" ] );
334 t("Check for something", "//[a]", ["foo", "baar"]);
339 ### Fires a native DOM event without going through jQuery ###
342 fireNative( node, eventType )
348 fireNative( jQuery("#elem")[0], "click" );
351 ### Add random number to url to stop caching ###
354 url( "some/url.php" );
360 url("data/test.html");
362 => "data/test.html?10538358428943"
365 url("data/test.php?foo=bar");
367 => "data/test.php?foo=bar&10538358345554"
371 ### Load tests in an iframe ###
373 Loads a given page constructing a url with fileName: `"./data/" + fileName + ".html"`
374 and fires the given callback on jQuery ready (using the jQuery loading from that page)
375 and passes the iFrame's jQuery to the callback.
378 testIframe( fileName, testName, callback );
384 callback( jQueryFromIFrame, iFrameWindow, iFrameDocument );
387 ### Load tests in an iframe (window.iframeCallback) ###
389 Loads a given page constructing a url with fileName: `"./data/" + fileName + ".html"`
390 The given callback is fired when window.iframeCallback is called by the page
391 The arguments passed to the callback are the same as the
392 arguments passed to window.iframeCallback, whatever that may be
395 testIframeWithCallback( testName, fileName, callback );
401 If you have any questions, please feel free to ask on the
402 [Developing jQuery Core forum](http://forum.jquery.com/developing-jquery-core) or in #jquery on irc.freenode.net.