1 page.title=Managing Projects from the Command Line 2 parent.title=Managing Projects 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 10 <ol> 11 <li><a href="#CreatingAProject">Creating an Android Project</a></li> 12 <li><a href="#UpdatingAProject">Updating a Project</a></li> 13 <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a> 14 <ol> 15 <li><a href="#CreatingManifestFile">Creating the manifest file</a></li> 16 <li><a href="#UpdatingLibraryProject">Updating a library project</a></li> 17 </ol> 18 </li> 19 <li><a href="#ReferencingLibraryProject">Referencing a Library Project</a> 20 <ol> 21 <li><a href="#DeclaringLibrary">Declaring library components in the manifest 22 file</a></li> 23 <li><a href="#depAppBuild">Building a dependent application</a></li> 24 </ol> 25 </li> 26 </ol> 27 28 <h2>See also</h2> 29 30 <ol> 31 <li><a href= 32 "{@docRoot}tools/testing/testing_otheride.html#CreateTestProjectCommand">Testing 33 from Other IDEs</a></li> 34 </ol> 35 </div> 36 </div> 37 38 <p>The <code>android</code> tool provides you with commands to create all three types of 39 projects. An Android project contains all of the files and resources that are needed to build a 40 project into an .apk file for installation. 41 42 <ul> 43 <li>An Android project contains all of the files and resources that are needed to build a project into 44 an .apk file for installation. You need to create an Android project for any application that you 45 want to eventually install on a device.</li> 46 47 <li>You can also designate an Android project as a library project, which allows it to be shared 48 with other projects that depend on it. Once an Android project is designated as a library 49 project, it cannot be installed onto a device.</li> 50 51 <li>Test projects extend JUnit test functionality to include Android specific functionality. For 52 more information on creating a test project, see <a href= 53 "{@docRoot}tools/testing/testing_otheride.html">Testing from other IDEs</a>.</li> 54 </ul> 55 56 57 <h2 id="CreatingAProject">Creating an Android Project</h2> 58 59 <p>To create an Android project, you must use the <code>android</code> tool. When you create a 60 new project with <code>android</code>, it will generate a project directory with some default 61 application files, stub files, configuration files and a build file.</p> 62 63 <p>To create a new Android project, open a command-line, navigate to the <code>tools/</code> 64 directory of your SDK and run:</p> 65 <pre> 66 android create project \ 67 --target <target_ID> \ 68 --name <your_project_name> \ 69 --path path/to/your/project \ 70 --activity <your_activity_name> \ 71 --package <your_package_namespace> 72 </pre> 73 74 <ul> 75 <li><code>target</code> is the "build target" for your application. It corresponds to an 76 Android platform library (including any add-ons, such as Google APIs) that you would like to 77 build your project against. To see a list of available targets and their corresponding IDs, 78 execute: <code>android list targets</code>.</li> 79 80 <li><code>name</code> is the name for your project. This is optional. If provided, this name 81 will be used for your .apk filename when you build your application.</li> 82 83 <li><code>path</code> is the location of your project directory. If the directory does not 84 exist, it will be created for you.</li> 85 86 <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This 87 class file will be created for you inside 88 <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code> 89 . This will also be used for your .apk filename unless you provide a <code>name</code>.</li> 90 91 <li><code>package</code> is the package namespace for your project, following the same rules as 92 for packages in the Java programming language.</li> 93 </ul> 94 95 <p>Here's an example:</p> 96 <pre> 97 android create project \ 98 --target 1 \ 99 --name MyAndroidApp \ 100 --path ./MyAndroidAppProject \ 101 --activity MyAndroidAppActivity \ 102 --package com.example.myandroid 103 </pre> 104 105 <p>Once you've created your project, you're ready to begin development. You can move your project 106 folder wherever you want for development, but keep in mind that you must use the <a href= 107 "{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (adb) — located in the 108 SDK <code>platform-tools/</code> directory — to send your application to the emulator (discussed 109 later). So you need access between your project solution and the <code>platform-tools/</code> folder.</p> 110 111 <p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the <code>tools/</code> directory 112 to your <code>PATH</code> environment variable.</p> 113 114 <p class="caution"><strong>Caution:</strong> You should refrain from moving the location of the 115 SDK directory, because this will break the SDK location property located in <code>local.properties</code>. 116 If you need to update the SDK location, use the <code>android update project</code> command. 117 See <a href="#UpdatingAProject">Updating a Project</a> for more information.</p> 118 119 <h2 id="UpdatingAProject">Updating a Project</h2> 120 121 <p>If you're upgrading a project from an older version of the Android SDK or want to create a new 122 project from existing code, use the <code>android update project</code> command to update the 123 project to the new development environment. You can also use this command to revise the build 124 target of an existing project (with the <code>--target</code> option) and the project name (with 125 the <code>--name</code> option). The <code>android</code> tool will generate any files and 126 folders (listed in the previous section) that are either missing or need to be updated, as needed 127 for the Android project.</p> 128 129 <p>To update an existing Android project, open a command-line and navigate to the 130 <code>tools/</code> directory of your SDK. Now run:</p> 131 <pre> 132 android update project --name <project_name> --target <target_ID> 133 --path <path_to_your_project> 134 </pre> 135 136 <ul> 137 <li><code>target</code> is the "build target" for your application. It corresponds to an 138 Android platform library (including any add-ons, such as Google APIs) that you would like to 139 build your project against. To see a list of available targets and their corresponding IDs, 140 execute: <code>android list targets</code>.</li> 141 142 <li><code>path</code> is the location of your project directory.</li> 143 144 <li><code>name</code> is the name for the project. This is optional—if you're not 145 changing the project name, you don't need this.</li> 146 </ul> 147 148 <p>Here's an example:</p> 149 <pre> 150 android update project --name MyApp --target 2 --path ./MyAppProject 151 </pre> 152 153 <h2 id="SettingUpLibraryProject">Setting up a Library Project</h2> 154 155 <p>A library project is a standard Android project, so you can create a new one in the same way 156 as you would a new application project. Specifically, you can use the <code>android</code> tool 157 to generate a new library project with all of the necessary files and folders.</p> 158 159 <p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory and 160 use this command:</p> 161 <pre class="no-pretty-print"> 162 android create lib-project --name <your_project_name> \ 163 --target <target_ID> \ 164 --path path/to/your/project \ 165 --package <your_library_package_namespace> 166 </pre> 167 168 <p>The <code>create lib-project</code> command creates a standard project structure that includes 169 preset property that indicates to the build system that the project is a library. It does this by 170 adding this line to the project's <code>project.properties</code> file:</p> 171 <pre class="no-pretty-print"> 172 android.library=true 173 </pre> 174 175 <p>Once the command completes, the library project is created and you can begin moving source 176 code and resources into it, as described in the sections below.</p> 177 178 <p>If you want to convert an existing application project to a library project, so that other 179 applications can use it, you can do so by adding a the <code>android.library=true</code> property 180 to the application's <code>project.properties</code> file.</p> 181 182 <h3 id="CreatingManifestFile">Creating the manifest file</h3> 183 184 <p>A library project's manifest file must declare all of the shared components that it includes, 185 just as would a standard Android application. For more information, see the documentation for 186 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> 187 188 <p>For example, the <a href= 189 "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library 190 project declares the Activity <code>GameActivity</code>:</p> 191 <pre> 192 <manifest> 193 ... 194 <application> 195 ... 196 <activity android:name="GameActivity" /> 197 ... 198 </application> 199 </manifest> 200 </pre> 201 202 <h3 id="UpdatingLibraryProject">Updating a library project</h3> 203 204 <p>If you want to update the build properties (build target, location) of the library project, 205 use this command:</p> 206 <pre> 207 android update lib-project \ 208 --target <em><target_ID></em> \ 209 --path <em>path/to/your/project</em> 210 </pre> 211 212 <h2 id="ReferencingLibraryProject">Referencing a Library Project</h2> 213 214 <p>If you are developing an application and want to include the shared code or resources from a 215 library project, you can do so easily by adding a reference to the library project in the 216 application project's build properties.</p> 217 218 <p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code> 219 directory and use this command:</p> 220 <pre> 221 android update project \ 222 --target <em><target_ID></em> \ 223 --path <em>path/to/your/project</em> 224 --library <em>path/to/library_projectA</em> 225 </pre> 226 227 <p>This command updates the application project's build properties to include a reference to the 228 library project. Specifically, it adds an <code>android.library.reference.<em>n</em></code> 229 property to the project's <code>project.properties</code> file. For example:</p> 230 <pre class="no-pretty-print"> 231 android.library.reference.1=path/to/library_projectA 232 </pre> 233 234 <p>If you are adding references to multiple libraries, note that you can set their relative 235 priority (and merge order) by manually editing the <code>project.properties</code> file and 236 adjusting the each reference's <code>.<em>n</em></code> index as appropriate. For example, assume 237 these references:</p> 238 <pre class="no-pretty-print"> 239 android.library.reference.1=path/to/library_projectA 240 android.library.reference.2=path/to/library_projectB 241 android.library.reference.3=path/to/library_projectC 242 </pre> 243 244 <p>You can reorder the references to give highest priority to <code>library_projectC</code> in 245 this way:</p> 246 <pre class="no-pretty-print"> 247 android.library.reference.2=path/to/library_projectA 248 android.library.reference.3=path/to/library_projectB 249 android.library.reference.1=path/to/library_projectC 250 </pre> 251 252 <p>Note that the <code>.<em>n</em></code> index in the references must begin at "1" and increase 253 uniformly without "holes". References appearing in the index after a hole are ignored.</p> 254 255 <p>At build time, the libraries are merged with the application one at a time, starting from the 256 lowest priority to the highest. Note that a library cannot itself reference another library and 257 that, at build time, libraries are not merged with each other before being merged with the 258 application.</p> 259 260 <h3 id="DeclaringLibrary">Declaring library components in the manifest file</h3> 261 262 <p>In the manifest file of the application project, you must add declarations of all components 263 that the application will use that are imported from a library project. For example, you must 264 declare any <code><activity></code>, <code><service></code>, 265 <code><receiver></code>, <code><provider></code>, and so on, as well as 266 <code><permission></code>, <code><uses-library></code>, and similar elements.</p> 267 268 <p>Declarations should reference the library components by their fully-qualified package names, 269 where appropriate.</p> 270 271 <p>For example, the <a href= 272 "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example 273 application declares the library Activity <code>GameActivity</code> like this:</p> 274 <pre> 275 <manifest> 276 ... 277 <application> 278 ... 279 <activity android:name="com.example.android.tictactoe.library.GameActivity" /> 280 ... 281 </application> 282 </manifest> 283 </pre> 284 285 <p>For more information about the manifest file, see the documentation for 286 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> 287 288 <h3 id="depAppBuild">Building a dependent application</h3> 289 290 <p>To build an application project that depends on one or more library projects, you can use the 291 standard Ant build commands and compile modes, as described in <a href= 292 "{@docRoot}tools/building/index.html">Building and Running</a>. The tools 293 compile and merge all libraries referenced by the application as part of 294 compiling the dependent application project. No additional commands or steps are necessary.</p> 295 296
