[Openchrome-devel] [Tutorial] Detailed instructions on how to backup, restore, compile, and install OpenChrome

[Kevin Brace]

Hi,

Okay, I had a request regarding the instructions on how to compile and install master branch OpenChrome device driver.
So I spent several hours writing this tutorial so that you can backup, restore, compile, and install OpenChrome on your own.
This is the way I do it, and I hope it is useful to you.
Please note that I primarily use Lubuntu 12.04 i386 for OpenChrome development purposes, and the instructions here are generally for Debian / Ubuntu branch of Linux.
I am not against other Linux distributions, but at least in my case, I mainly use Lubuntu 12.04.
The line starting with '$' signifies a terminal command, and it should be removed when it is being entered into the terminal command line.

1) Downloading OpenChrome

Before starting, create an appropriate directory (folder) so that you can play in the "sandbox" safely.

$ mkdir OpenChrome_Test

The name I picked, "OpenChrome_Test" can be anything (pick your own favorite directory name).
In order to download OpenChrome master branch code, you need to have Git installed.
 
$ sudo apt-get install git-core

This may not be necessary, but it is probably safer to initialize Git now if it has never been.

$ git init

Also, the dependent packages for OpenChrome need to be installed as well.

$ sudo apt-get build-dep xserver-xorg-video-openchrome

Please note that, at least in Ubuntu, the package for OpenChrome is called xserver-xorg-video-openchrome, not xf86-video-openchrome.
Now clone the OpenChrome repository to your local computer storage device.

$ git clone git://anongit.freedesktop.org/openchrome/xf86-video-openchrome

After you finished cloning the OpenChrome repository, enter the resulting directory.

$ cd xf86-video-openchrome


2) Compiling OpenChrome (debug build)

Before you can compile the code, the compilation and other scripts need to be generated.

$ ./autogen.sh --prefix=/usr --enable-debug --enable-xv-debug --enable-viaregtool 

"--enable-viaregtool" instructs "make" to generate via_regs_dump under xf86-video-openchrome/tools.
If there were no errors, OpenChrome can now be compiled.

$ make

If OpenChrome compiles without errors, you are now ready to install OpenChrome.


3) (Optional) Compiling OpenChrome (release build)

If you wanted to do a release build of OpenChrome instead of a debug build, enter the following commands into the terminal command line..

$ ./autogen.sh --prefix=/usr

If there were no errors, OpenChrome can now be compiled.

$ make

If OpenChrome compiles without errors, you are now ready to install OpenChrome.


4) Backing up OpenChrome

There is a reason why you are recommended to make a backup of the original OpenChrome.
Unfortunately, things do go wrong, and in the worst case, your OS may not boot at all (i.e., text mode only, hang, or freeze).
This is how I backup the original OpenChrome files in Ubuntu.
Switch to the directory where the OpenChrome xorg DDX (Device Dependent X) device driver is located.

$ cd /usr/lib/xorg/modules/drivers

Check the files located in this directory.

$ ls -l

Now make a backup of the original xorg DDX OpenChrome device driver.

$ sudo mv openchrome_drv.so Original_openchrome_drv.so

Please note that "Original_" portion can be whatever you wish.
Switch to the directory where the Xv related OpenChrome device drivers are located.

$ cd /usr/lib

Check the files located in this directory.

$ ls libchrome*.* -l

Now make a backup of the original Xv related OpenChrome device drivers.

$ sudo mv libchromeXvMC.so Original_libchromeXvMC.so
$ sudo mv libchromeXvMC.so.1 Original_libchromeXvMC.so.1
$ sudo mv libchromeXvMC.so.1.0.0 Original_libchromeXvMC.so.1.0.0
$ sudo mv libchromeXvMCPro.so Original_libchromeXvMCPro.so
$ sudo mv libchromeXvMCPro.so.1 Original_libchromeXvMCPro.so.1
$ sudo mv libchromeXvMCPro.so.1.0.0 Original_libchromeXvMCPro.so.1.0.0


5) Installing OpenChrome

You are ready to install OpenChrome.
Switch to the original directory where you originally cloned the OpenChrome.

$ cd /home/("Your user name")/OpenChrome_Test

Please find the above location on your own since it can vary. 
Enter the cloned OpenChrome directory.

$ cd xf86-video-openchrome

Install OpenChrome.

$ sudo make install

If the installation script runs without errors, OpenChrome is now installed.
If you want to make it "look" perfect, enter the following commands into the terminal command line.

$ cd /usr/lib/xorg/modules/drivers
$ sudo rm openchrome_drv.la
$ sudo chmod 644 openchrome_drv.so
$ cd /usr/lib
$ sudo rm libchromeXvMC.la
$ sudo rm libchromeXvMCPro.la
$ sudo chmod 644 libchromeXvMC.so.1.0.0
$ sudo chmod 644 libchromeXvMCPro.so.1.0.0

Now, OpenChrome is installed.
Reboot your computer.
If you are successful, it should boot normally.


6) (Optional) Restoring original OpenChrome

This is how the original OpenChrome files can be restored.
It is possible that you are doing this because the newly installed OpenChrome did not work correctly.
If you are having issues booting your OS, you may have to enter a fail safe mode where you at least have terminal command line access.
Switch to the directory where the OpenChrome xorg DDX device driver is located.

$ cd /usr/lib/xorg/modules/drivers

Check the files located in this directory.

$ ls -l

Restore the original OpenChrome xorg DDX device driver.

$ sudo rm openchrome_drv.so
$ sudo cp Original_openchrome_drv.so openchrome_drv.so

Switch to the directory where the Xv related OpenChrome device drivers are located.

$ cd /usr/lib

Check the files located in this directory.

$ ls libchrome*.* -l
$ ls Original_libchrome*.* -l

Restore the original Xv related OpenChrome device drivers.

$ sudo rm libchromeXvMC.so
$ sudo rm libchromeXvMC.so.1
$ sudo rm libchromeXvMC.so.1.0.0
$ sudo rm libchromeXvMCPro.so
$ sudo rm libchromeXvMCPro.so.1
$ sudo rm libchromeXvMCPro.so.1.0.0
$ sudo cp Original_libchromeXvMC.so libchromeXvMC.so
$ sudo cp Original_libchromeXvMC.so.1 libchromeXvMC.so.1
$ sudo cp Original_libchromeXvMC.so.1.0.0 libchromeXvMC.so.1.0.0
$ sudo cp Original_libchromeXvMCPro.so libchromeXvMCPro.so
$ sudo cp Original_libchromeXvMCPro.so.1 libchromeXvMCPro.so.1
$ sudo cp Original_libchromeXvMCPro.so.1.0.0 libchromeXvMCPro.so.1.0.0

Now, the original OpenChrome restored.
Reboot your computer.
If you are successful, it should boot normally.


7) (Optional) Updating your cloned local OpenChrome repository

This method is the sure way to do it (i.e., the only way I know how to do it).
Switch to the original directory where you originally cloned the OpenChrome.

$ cd /home/("Your user name")/OpenChrome_Test

Please find the above location on your own since it can vary. 
Enter the cloned OpenChrome directory.

$ cd xf86-video-openchrome

Display the past commits to the OpenChrome repository.

$ git log

Press 'Page Down" and 'Page Up' to scroll through the past commit logs and 'q' to exit.
When a commit is made, it accompanies a commit ID.
Use the commit ID to reset the repository to a past commit point ("hard reset").

$ git reset --hard ("Commit ID")

For example, to go back to commit 3d8aa5d0be2be6e874a11e898cfc0abdf32307dc, enter the following.

$ git reset --hard 3d8aa5d0be2be6e874a11e898cfc0abdf32307dc

Please note that if you made changes to your local copy of the OpenChrome source code, "hard reset" will erase them, so be careful.
Since it is likely that OpenChrome will go through heavy development moving forward, in order to obtain the latest commits, enter the following.

$ git pull

This will update your cloned OpenChrome repository on your local storage device.
You can confirm this by looking at the log.

$ git log

You can also see the code change between commits.

$ git log -p

If you wanted to compile the code again, please go back to Section 2 or 3.

--

I hope this tutorial is useful to you, and it can get more people to participate in testing OpenChrome.

Kevin Brace (OpenChrome project maintainer)