
= Getting LinuxCNC

This section describes the recommended way to download
and make a fresh install of LinuxCNC.  There are also
<<_alternate_install_methods,Alternate Install Methods>> for the
adventurous.  If you have an existing install that you want to upgrade,
go to the <<_updating_linuxcnc,Updating LinuxCNC>> section instead.

Fresh installs of LinuxCNC are most easily created using the Live/Install
Image.  This is a hybrid ISO filesystem image that can be written to a
USB storage device or a DVD and used to boot a computer.  At boot time you
will be given a choice of booting the "Live" system (to run LinuxCNC
without making any permanent changes to your computer) or booting the
Installer (to install LinuxCNC and its operating system onto your
computer's hard drive).

The outline of the process looks like this:

* Download the Live/Install Image.
* Write the image to a USB storage device or DVD.
* Boot the Live system to test out LinuxCNC.
* Boot the Installer to install LinuxCNC.


== Download the image

This section describes some methods for downloading the Live/Install
Image.


=== Normal Download

Download the Live/Install CD by clicking here:

http://www.linuxcnc.org/linuxcnc-2.7-wheezy.iso


=== Download using zsync

zsync is a download application that efficiently resumes interrupted
downloads and efficiently transfers large files with small modifications
(if you have an older local copy).  Use zsync if you have trouble
downloading the image using the <<_normal_download,Normal Download>>
method.

zsync in Linux::
    Install zsync using your favourite package management
    application such as Synaptic or, by running `sudo apt-get install
    zsync` in a terminal.  Then run this command to download (in a
    terminal): `zsync http://www.linuxcnc.org/linuxcnc-2.7-wheezy.iso.zsync`

zsync in Windows::
    There is a Windows port of zsync.  It works as a
    console application, just like the Linux version, so
    get out that Command Prompt.  It can be downloaded from:
    https://www.assembla.com/spaces/zsync-windows/documents


=== Verify the image

After downloading, verify the checksum of the image to ensure integrity.
In a terminal, run `md5sum linuxcnc-2.7-wheezy.iso` or `sha256sum
linuxcnc-2.7-wheezy.iso`, and compare to these checksums:

-----
md5sum: 3aa031895ac74a81d0639b09cd812c22
sha256sum: c47d8c8432b710f0c28f6b98389af6ad4c429d024501335e95a2646a894f45e9
-----

Verify md5sum on Windows or Mac::
+
Windows and Mac OS X do not come with an md5sum program, but there are
alternatives.  More information can be found at:
+
https://help.ubuntu.com/community/HowToMD5SUM


== Write the image to a bootable device

The LinuxCNC Live/Install Image is a hybrid ISO image which can be written
directly to a USB storage device (flash drive) or a DVD and used to boot
a computer.  The image is too large to fit on a CD.

Writing the image to a USB storage device in Linux::
    * Connect a USB storage device (for example a flash drive or thumb
      drive type device).
    * Determine the device file corresponding to the USB flash drive.
      This information can be found in the output of `dmesg` after
      connecting the device.  `/proc/partitions` may also be helpful.
    * Use the `dd` command to write the image to your USB storage device.
      For example, if your storage device showed up as `/dev/sde`,
      then use this command:
      +
-----
dd if=linuxcnc-2.7-wheezy.iso of=/dev/sde
-----

Writing the image to a DVD in Linux::

 . Insert a blank DVD into your burner. A 'CD/DVD Creator' or
   'Choose Disc Type' window will pop up. 
   Close this, as we will not be using it.
 . Browse to the downloaded image in the file browser.
 . Right click on the ISO image file and choose Write to Disc.
 . Select the write speed.  It is
   recommended that you write at the lowest possible speed.
 . Start the burning process.
 . If a 'choose a file name for the disc image' window pops up, just pick OK.

Writing the image to a DVD in Windows::

 . Download and install Infra Recorder, a free and open source image
   burning program: http://infrarecorder.org/
 . Insert a blank CD in the drive and select Do nothing or Cancel if an
   auto-run dialog pops up.
 . Open Infra Recorder, and select the 
   'Actions' menu, then 'Burn image'.


== Testing LinuxCNC

With the USB storage device plugged in or the DVD in the DVD drive, the
shut down the computer then turn the computer back on. This will boot
the computer from the Live/Install Image and choose the Live boot option.
Once the computer has booted up you can try out LinuxCNC without installing
it. You can not create custom configurations or modify most system
settings like screen resolution unless you install LinuxCNC.

To try out LinuxCNC from the Applications/CNC menu pick LinuxCNC. Then select
a sim configuration to try out.

To see if your computer is suitable for software step pulse generation
run the Latency Test as shown <<latency-test,here>>.


== Installing LinuxCNC

To install LinuxCNC from the LiveCD select 'Install (Graphical)' at bootup.


== Updates to LinuxCNC (((Updates to LinuxCNC)))

With the normal install the Update Manager will notify you of updates
to LinuxCNC when you go on line and allow you to easily upgrade with no
Linux knowledge needed.
It is OK to upgrade everything except the operating system when asked to.

WARNING: Do not upgrade the operating system if promped to do so.


== Install Problems

In rare cases you might have to reset the BIOS to default settings if
during the Live CD install it cannot recognize the hard drive 
during the boot up.


== Alternate Install Methods

The easiest, preferred way to install LinuxCNC is to use the Live/Install
Image as described above.  That method is as simple and reliable as we
can make it, and is suitable for novice users and experienced users alike.

In addition, for experienced users who are familiar with Debian system
administration (finding install images, manipulating apt sources, changing
kernel flavors, etc), new installs are supported on following platforms:

[options="header"]
|===================================================================
| Distribution   | Architecture | kernel     | Typical use
| Debian Wheezy  | i386         | RTAI       | machine control & simulation
| Debian Wheezy  | amd64 & i386 | Preempt-RT | machine control & simulation
| Debian Wheezy  | amd64 & i386 | vanilla    | simulation only
| Ubuntu Precise | i386         | RTAI       | machine control & simulation
| Ubuntu Precise | amd64 & i386 | vanilla    | simulation only
| Ubuntu Lucid   | i386         | RTAI       | machine control & simulation
| Ubuntu Lucid   | amd64 & i386 | vanilla    | simulation only
|===================================================================

The RTAI kernels are available for download from the linuxcnc.org
debian archive.  The apt source is:

    * Debian Wheezy: `deb http://linuxcnc.org wheezy base`
    * Ubuntu Precise: `deb http://linuxcnc.org precise base`
    * Ubuntu Lucid: `deb http://linuxcnc.org lucid base`

The Preempt-RT kernels are available from the regular debian.org archive,
as part of Debian Wheezy.  No special apt source is needed.  The packages
are called `linux-image-rt-amd64` and `linux-image-rt-686-pae`.


=== Installing on Debian Wheezy (with Preempt-RT kernel)

* Install Debian Wheezy (Debian version 7), either i386 or amd64.
  You can download the installer here:
  https://www.debian.org/CD/http-ftp/#stable

* Run `sudo apt-get update` followed by `sudo apt-get dist-upgrade` to
  bring the machine up to date with the latest packages in Debian Wheezy.

* Install the Preempt-RT kernel and modules by running: `sudo
  apt-get install linux-image-rt-amd64` or `sudo apt-get install
  linux-image-rt-686-pae`.

* Reboot, and make sure you boot into the Preempt-RT kernel. When you
  log in, verify that `uname -r` says 3.2.0-4-rt-686-pae.

* Add the LinuxCNC Archive Signing Key to your apt keyring by running
  `sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-key 8f374fef`

* Add a new apt source that looks like this: `deb http://linuxcnc.org/
  wheezy base 2.7-uspace`

* Run `sudo apt-get update` again to fetch the package list from
  linuxcnc.org.

* Run `sudo apt-get install linuxcnc-uspace`.

* Machine away!


=== Installing on Ubuntu Precise

* Install Ubuntu Precise 12.04 x86 (32-bit). Any flavor should
  work (regular Ubuntu, Xubuntu, Lubuntu, etc). 64-bit (AMD64)
  is currently not supported. You can download the installer here:
  http://releases.ubuntu.com/precise/

* Run `sudo apt-get update` followed by `sudo apt-get dist-upgrade` to
  bring the machine up to date with the latest packages in Ubuntu Precise.

* Add the LinuxCNC Archive Signing Key to your apt keyring by running
  `sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-key 8f374fef`

* Add a new apt source that looks like this: `deb http://linuxcnc.org/
  precise base 2.7-rtai`

* Run `sudo apt-get update` again to fetch the package list from
  linuxcnc.org.

* Install the RTAI kernel and modules by running: `sudo apt-get install
  linux-image-3.4-9-rtai-686-pae rtai-modules-3.4-9-rtai-686-pae`

* If you want to be able to build LinuxCNC from source using the git repo,
  also run `sudo apt-get install linux-headers-3.4-9-rtai-686-pae`

* Reboot, and make sure you boot into the rtai kernel. When you log in,
  verify that `uname -r` says 3.4-9-rtai-686-pae.

* Run `sudo apt-get install linuxcnc`.

* Machine away!
