XEmacs -- Emacs: The Next Generation
English
German
Japanese
America
Asia
Australia
Europe
 
     Searching XEmacs
Quick Links About XEmacs Getting XEmacs Customizing XEmacs Troubleshooting XEmacs Developing XEmacs
      

XEmacs Mercurial Repository

As of October, 2011, all the XEmacs repositories have moved to Mercurial repositories on bitbucket.org from which you may browse the latest checked-in code. This page describes access to those resources.

Please note: This page was hacked up quickly by copying and editing the corresponding page for CVS. If you spot any CVS-isms or other statements that are not correct for the Mercurial repository, please report it as a bug to the XEmacs Developers.

This site has a collection of Mercurial trees for XEmacs, a feature-packed text-editing environment based on Lisp. For general information about XEmacs, check out the XEmacs main WWW server.

Quick Start Guide

To get the official (21.5) development sources, do:

      hg clone https://bitbucket.org/xemacs/xemacs
    

This may include a few bleeding edge patches that are still under review (and in some cases may already have been vetoed or be known to cause crashes and other showstoppers). However as of XEmacs 21.5.31 (the first GPLv3+ release, 2011-04-29) the code base is reasonably stable.

The XEmacs Lisp packages are now unbundled, and are available from the Mercurial repository. Older versions of XEmacs, including the currently stable version (21.4) may also be checked out from Mercurial repository.

Each of these components are available separately as non-CVS tarballs via HTTP and FTP. Here are the current HTTP URLs:

If you prefer FTP for some reason, simply change the URL scheme from "http" to "ftp".


What is Mercurial?

Mercurial is a modern version control system (VCS) that not only keeps track of older versions also handles branching and distributed development well. Unlike CVS or Subversion (the defacto industry-standard source code control system for open source software projects), every Mercurial checkout is a full repository, containing all of the project's history. Because the archives are compressed, a full repository (back to 21.5.0) requires much less than twice the space of the source tree alone. Unlike many other VCSes (including CVS and git) Mercurial is perfectly happy to serve remote clients over an ordinary HTTP connection, using an unmodified httpd and a tiny CGI. This means that you can easily share your version-controlled patches with others, even if they are not accepted for the mainline.

Regular contributors to XEmacs are strongly encouraged to get Mercurial write access to the source repository. This distributes most of the patch-tracking work to those most qualified to do it, namely the patch authors. XEmacs source code maintenance is basically organized on the bazaar model - we'd like to have as many people as possible, including you, making high quality contributions to the source code, in parallel. But even if you are just a lurker with no desire to make any modifications to the tree, Mercurial gives you a painless way to upgrade between versions.

By current standards, these trees are moderate in size. XEmacs 21.5 sources will take up 80 MB of hard drive space, before compilation, the Mercurial metadata and archive about as much. A typical build will add about 60 MB of build products, for a total of about 220 MB required for core development. Add in the lisp packages tree (another 120 MB of source, with compiled Lisp taking about 70MB) in your calculations if you're interested in messing with them too.


Using the XEmacs Mercurial server

If you're interested in using the XEmacs Mercurial trees directly, you'll need to install Mercurial. Mercurial is highly portable because it is entirely written in Python. Binary packages are available for most platforms, either through native package distributions or from Selenic.

Unlike many centralized servers, XEmacs's Mercurial repository does not require login for cloning the repository. (Note: for modern distributed VCSes, whole repository is duplicated and can stand alone, so we use the word "clone" rather than "checkout". "Checkout" is used to describe the operation of copying files from the repository archive to the working copy, whether to revert undesirable changes in a single file, or to switch the entire working copy over to another branch.) The clone operation is simple.

First cd to the place you want to put the tree, and actually clone the repository.

chibi$ hg clone https://bitbucket.org/xemacs/xemacs-beta xemacs-21.5
(churn, churn, churn)
    

And voila! One xemacs-21.5 directory complete with the latest versions of the base code. Packages are separate, of course.

The last argument xemacs-21.5 gives the name of the directory to use as a workspace. The repository metadata and archives go in the .hg subdirectory, and there will usually be a .hgignore file containing regexps matching names of files to ignore for version control purposes. If the tree root name (here xemacs-21.5) is omitted, it will be defaulted to the basename of the URL being cloned.

You probably want to create a ~/.hgrc file to configure your local defaults. At least it's worth setting your Mercurial username:


[ui]
username = J. Random Hacker <jrhacker@example.com>
    

so that any local commits to your own repository look nice. (Feel free to commit what you like, it's your repository. If you expect to contribute upstream, however, you may want to keep a separate "pristine" workspace or learn about named branches.)

When there is an upstream update, you can get the whole skinny quick, fast and relatively painlessly with the following command (executed from the directory created by hg clone).

chibi$ hg pull -u
    

The -u switch automatically updates your workspace to correspond to the tip.

If you have local changes that you'd like to keep under version control, you can either use a separate repository.

Just how much do you want to bleed?

XEmacs developers push their commits on an asynchronous basis. The idea is to keep those actively coding on the same page by making everyone's most recent code available in a central place. There is no strong guarantee that the tip of the default Mercurial branch even compiles for anyone. This means that if you blindly do a hg pull -u, there is a good chance that what you get is not functional.

There are several ways to deal with the churn.

  • Since you have the whole repository available, you can simply revert to an earlier revision.
    chibi$ hg checkout -r 1234
    	
    If this mechanism satisfies you, you may even want to clone and update to the completely unfiltered repository that the active developers are committing to:
    chibi$ hg clone https://bitbucket.org/xemacs/xemacs xemacs-21.5
    	
  • You can also take advantage of the review process, and use the xemacs-beta repository as described above.
  • Finally, the most conservative approach is to checkout only the official releases. These are identical to the tarballs distributed by xemacs.org, and are identified in both the xemacs and xemacs-beta repositories by tags of the form rX-Y-Z, corresponding to the version number X.Y.Z (or X.Y-bZ). X is the major version, Y the minor version, and Z the micro version or patchlevel.

In general, tags are admissible anywhere a revision number or hash is allowed. To checkout a particular revision use the checkout command with the -r <TAG> option to. Therefore, to update to 21.5 beta 30 (but no further), you'd type:

chibi$ hg checkout -r r21-5-30
    

The most recent patchlevel or beta release is identified by the tag rX-Y-latest-beta.

For more info, check the Mercurial documentation:


Package system

For those of you wishing to work with XEmacs 21, you should probably know about our packaging system. All the details are available here.

Web Access

You can browse the repositories simply by accessing the repositories with any web browser.


Commit (R/W) access to the Mercurial tree

Anybody who has become reasonably well-known to the XEmacs Reviewers can get access to commit to the repository. This has the following advantages:

  • The revision history will contain the true author of a change, which makes tracking changes easier, and gives credit where credit is due.
  • Committers are more likely to take responsibility for their changes when they are directly modifying the repository themselves.

To qualify to be a committer, you should have a history of submitting successful patches to xemacs-patches

Currently we are adding new committers using the following method (which may change):

  1. Make sure ssh (version 1 or 2) is installed on your computer.
  2. Get yourself a ssh public key. Here is some unsolicited advice on maintaining your ssh key:

    In general, you should only have ONE identity that you expose to the outside world. Create only ONE key pair: ~/.ssh/identity and ~/.ssh/identity.pub for version 1. Or for version 2, one of either ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa and ~/.ssh/id_dsa.pub with ssh-keygen, and change the comment to something more meaningful like your email address. Your ssh public key is a lot like a business card.

    For example, I modified the comment in my version 1 public key using

    ssh-keygen -c -C 'Steve Youngs <youngs@xemacs.org>'
    	

    SSH version 2 is slightly different. If you try the above command on a version 2 key you'll get an error saying that comments are only supported for version 1 keys. Don't believe everything you read, you can have a comment in a version 2 key. You just have to add the comment when you create the key:

    ssh-keygen -t dsa -C 'Steve Youngs <youngs@xemacs.org>'
    	

    After you have created your keys, copy the ~/.ssh/identity or ~/.ssh/id_dsa or ~/.ssh/id_rsa file to all the machines you run ssh from.

    Also, append your public key file ~/.ssh/identity.pub to the ~/.ssh/authorized_keys file for SSH 1 or ~/.ssh/id_(dsa|rsa).pub to ~/.ssh/authorized_keys2 on all the machines you run ssh to.

    When people ask you for your public ssh key, just send them the contents of ~/.ssh/identity.pub or ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub.

  3. If you do not already have a Bitbucket account, you'll need to go to the Bitbucket web site (http://bitbucket.org/) and get an account. Register the ssh key you've just created with your account.
  4. Send the Mercurial Administrator your Bitbucket. The administrator will take care of the administrivia to give you access.
  5. Add this stanza to your ~/.ssh/config file (create it if necessary):

    Host bitbucket.org
    	User		user
    	ForwardX11	no
    	ForwardAgent	no
    	
  6. Once your access is set up, you can pull from and push to the repository via the alternate address:

    ssh://hg@bitbucket.org/xemacs/xemacs
    	

    If you've already checked out via HTTPS, you can redirect your local repository to ssh access by editing the file .hg/hgrc, which should contain a line:

    default = https://bitbucket.org/xemacs/xemacs
    	

    Change that line to:

    default = ssh://hg@bitbucket.org/xemacs/xemacs
    	
 
 

Not conform with <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Automatically validated by PSGML