git.hungrycats.org Git - xscreensaver/blob - android/project/GLWallpaperService/readme-contribute.txt

   1 Project Setup - GLWallpaperService
   2 ==================================
   3
   4 Discussion Group:
   5 http://groups.google.com/group/glwallpaperservice
   6
   7 Repository:
   8 https://github.com/markfguerra/GLWallpaperService/
   9
  10 Intended Audience
  11 -----------------
  12 This document is for developers who want to improve GLWallpaperService. It shows you how to download the source code to to improve it (or break it) as you please using Eclipse.
  13 If you're only interested in using the software to make an OpenGL Wallpaper, this isn't for you. Instead, look at readme.txt for info on how to get and install the Jar.
  14
  15
  16 Install required software
  17 -------------------------
  18 To start, make sure install Eclipse the latest Android SDK are installed. Optionally, install git. Follow the instructions provided by those software projects to do so.
  19     Eclipse:     http://wiki.eclipse.org/FAQ_Where_do_I_get_and_install_Eclipse%3F
  20     Android SDK: http://developer.android.com/sdk/installing.html
  21         Git:         http://git-scm.com/
  22
  23 Also, if you plan on using git, we recommend you make an account on github.
  24         http://github.com/
  25
  26
  27 Folder Setup
  28 ------------
  29 We are going to make two folders in this document. One will contain the code itself, and another will contain the Eclipse workspace. If you prefer that they both be in the same folder, do so. As if I could stop you ;)
  30
  31 Go to where you're putting all this stuff.
  32     cd /path/to/your/folder
  33
  34 Make a folder for your workspace.
  35     mkdir workspace
  36
  37
  38 Get the code
  39 ------------
  40 Download the source code. You can do so using git or just a regular old download.
  41
  42 For a direct download, go here. Extract the zip into a sub folder:
  43     https://github.com/markfguerra/GLWallpaperService/zipball/master
  44
  45 If you use github, please fork this code from their web interface:
  46     https://github.com/markfguerra/GLWallpaperService
  47
  48 Then you want to make a local clone of your github fork. Github will provide you with your own Url. My clone command looks like this:
  49     git clone git@github.com:markfguerra/GLWallpaperService.git
  50
  51 A new folder will be created automatically, called GLWallpaperService/ containing your source code.
  52
  53 Visit this link if you need help using github:
  54     http://help.github.com/
  55
  56
  57 Start Eclipse
  58 -------------
  59 Open Eclipse and choose the folder you just created for your workspace. When it finishes loading, click the Arrow to go to the workbench.
  60
  61
  62 Set up the Android SDK
  63 ----------------------
  64 To set up the Android SDK for this project:
  65 In the menu, go to Eclipse->Preferences. Go to the Android section.
  66 Give it the location of your Android SDK folder. Give it a minute to figure things out.
  67 Select Android 2.1 (Api level 7) then click Ok.
  68
  69
  70 Import the code into the workspace
  71 ----------------------------------
  72 In the Eclipse menu, choose File->New->"Android Project"
  73 Choose "Create new project from existing source"
  74 For the location click browse and select the "GLWallpaperService" folder. To be clear, this is a sub-folder of the folder that contains the LICENSE file.
  75 Select "Android 2.1-update1" as your build target. This is API Level 7.
  76 For the Project Name, type "GLWallpaperService"
  77 Repeat these steps for the "GLWallpaperTest" folder. Use the project name "GLWallpaperTest"
  78
  79 The code will now be in your workspace.
  80
  81
  82 Resolving build errors
  83 ----------------------
  84 Most people should have a working project at this point. However, some folks encounter build errors when they first import the code into their workspace. There are a couple of tricks to help you fix them.
  85 First and foremost, make sure you have the latest versions of the Android SDK and Eclipse plugin. This is important, because older versions of the developer tools handle Library Projects differently, so if you have an old version this may cause problems.
  86 You may have to fix the Project Properties. Right-click on the "GLWallpaperService" project in the Package Explorer. Select "Android Tools"->"Fix Project Properties".
  87 Also fix the project properties for "GLWallpaperTest" the same way.
  88 In the menu, click on Project->Clean to clean all projects.
  89 In Package Explorer, right-click on the GLWallpaperService project and click on "Refresh". Do the same for GLWallpaperTest.
  90 You may need to click on Project->Clean to clean all projects again after the refresh.
  91 Your errors should go away at this point. If not, try using a programming Q&A site such as stackoverflow.com and also search Google.
  92
  93
  94 To Run
  95 ------
  96 Save your work. By default, saving will also compile your code in Eclipse.
  97
  98 Plug in your Android Device to your computer, if you have one. If you don't plug in an Android device, the emulator will launch when you run the code. You may need create an Android Emulator if you havn't done so already.
  99
 100 In the Menu, choose Run->"Run Configurations".
 101 Choose "Android Application"
 102 Click on the "New" button. This is the button with the plus sign on it.
 103 The name of the run configuration is New_configuration. Change it if you like.
 104 Click "Browse..." to choose a project. Select GLWallpaperTest. This is a sample wallpaper that comes with the code.
 105 Click Apply. Click Run.
 106 The wallpaper will now install on your device or emulator. Use the regular Android live wallpaper picker to select "GL Wallpaper Test Project". You should see a 3D rotating cube.
 107
 108 Now that your run configuration is set up, you can run New_configuration any time by using the Toolbar icon.
 109
 110
 111 Creating GLWallpaperService.jar
 112 -------------------------------
 113 Do the following to create the JAR file, which is convenient for use in projects.
 114 In the Eclipse menu, click File -> Export
 115 Choose "JAR File"
 116 On the "JAR Export" screen, choose only GLWallpaperService.java. You do not need to include other files.
 117 Make note of where the JAR will be saved and click Finish
 118
 119
 120 Contribute your code
 121 --------------------
 122 If you do something cool with this software, we would love it if you would share your changes with us. Even if your changes still need some polishing. Don't worry, we're friendly :)
 123
 124 If you are using git and github, push your changes to your fork and send us a pull request. If you're not using those fancy things, we want to hear from you anyway. Send us a message and we'll work something out.
 125
 126 Thanks for your interest in this project. Good luck coding!
 127