Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 161 lines (119 sloc) 6.828 kb
903557a @jverkoey Lots of content.
jverkoey authored
1 ---
49a9996 @jverkoey Various minor touchups to the article names and content.
jverkoey authored
2 title: Introduction
903557a @jverkoey Lots of content.
jverkoey authored
3 css: grid
4 ---
5
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
6 Introduction
7 ============
8
9 Before you begin using Three20 in your project, you should decide what directory layout works
10 best for you.
11
12 Recommended: Shared Layout
13 --------------------------
14
15 In this layout, Three20 is shared between multiple projects. If you need to make project-specific
16 modifications to Three20, use git branches.
17
18 If you are unfamiliar with git, it's highly recommended that you learn the basics in order to
19 take advantage of this directory layout.
20
21 ### Directories
22
23 three20
24 projects/app1
25 projects/app2
26
27 ### Example workflow
28
29 ."brush: bash"
30 # Work on app1
31 > cd three20
32 three20 > git checkout app1 # Check out app1's branch of modifications
33 three20 > open ../projects/app1/app1.xcodeproj # Open app1 in Xcode
34
35 # Work on app2
36 three20 > git checkout app2 # Check out app2's branch of modifications
ea1093b @defragged Fixed comment referring to app1 when the command references app2.
defragged authored
37 three20 > open ../projects/app2/app2.xcodeproj # Open app2 in Xcode
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
38
39 # Create a new app
40 three20 > git checkout -b app3 master # Create a new branch, 'app3', at master
41 # <Create a new Xcode project in projects/app3>
42 # <Add Three20 to the new Xcode project using ttmodule>
43
44 # Update three20 when a new release is made
45 three20 > git fetch # Get the latest updates from Github
46 three20 > git rebase origin/master master # Fast-forward the local release to the latest release
47 three20 > git rebase master app1 # Update each app individually, fixing any merge conflicts
48
49 Submodule Layout
50 ----------------
51
52 In this layout, Three20 lives directly within each project's folder as a git submodule. This
53 layout can be useful if you don't plan to make modifications to Three20.
54
55 ### Directories
56
57 projects/app1
58 projects/app1/three20
59 projects/app2
60 projects/app2/three20
61
62 ### Example workflow
63
64 ."brush: bash"
65 # Add Three20 to app1
66 > cd projects/app1
67 projects/app1 > git submodule add git://github.com/facebook/three20.git three20
68 projects/app1 > git submodule init
69 projects/app1 > git add three20
70 projects/app1 > git commit -m "Add Three20 submodule"
903557a @jverkoey Lots of content.
jverkoey authored
71
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
72 Add Three20 to your project
73 ===========================
903557a @jverkoey Lots of content.
jverkoey authored
74
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
75 There are two primary means of adding Three20 to your project. The first method is recommended
76 and will automatically add Three20's libraries to your project and set up the necessary project
77 settings. Sometimes this first method will fail, so you can fall back on the second method
78 to add Three20 to your project by hand.
7d34801 @jverkoey Add plenty of content.
jverkoey authored
79
903557a @jverkoey Lots of content.
jverkoey authored
80 Automatically add Three20 to your project
81 -----------------------------------------
82
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
83 Three20 includes a python script that adds Three20 to Xcode iOS projects. Running it without
84 any arguments will print the script's help guide.
903557a @jverkoey Lots of content.
jverkoey authored
85
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
86 ."brush: bash"
903557a @jverkoey Lots of content.
jverkoey authored
87 > python three20/src/scripts/ttmodule.py
88
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
89 In order to add Three20 to your project, it's recommended that you do the following:
903557a @jverkoey Lots of content.
jverkoey authored
90
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
91 ."brush: bash"
e8f98ce @jverkoey Style update and begin rewriting the branching model article.
jverkoey authored
92 > python three20/src/scripts/ttmodule.py -p path/to/myProject.xcodeproj Three20
903557a @jverkoey Lots of content.
jverkoey authored
93
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
94 This will add the [Three20](/module/three20) module and all of its dependencies to your project.
95
96 If your target's name does not match your project's name, you will need to set it explicitly.
97
98 ."brush: bash"
99 > python three20/src/scripts/ttmodule.py -p path/to/myProject.xcodeproj:myTargetName Three20
100
101 If the script displays errors, it's possible that your project is located in a folder
102 with non-standard characters, such as spaces, that aren't being escaped properly. If this happens,
103 it might be easiest to move your project to a path that doesn't contain spaces. If this is
104 not an option, you can follow the manual directions below.
105
106 This screencast will walk you through the above process with the "Shared Layout" project layout.
107
75c6e3d @jverkoey New site-wide TOC for articles and documentation.
jverkoey authored
108 <iframe title="YouTube video player" width="798" height="467" src="http://www.youtube.com/embed/-0-E-Z0fihg?hd=1" frameborder="0" allowfullscreen></iframe>
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
109
110 Manually add Three20 to your project
111 ------------------------------------
112
113 1. Locate the "Three20.xcodeproj" file under "`three20/src/Three20/`". Drag Three20.xcodeproj and
114 drop it onto the root of your Xcode project's "Groups and Files" sidebar. A dialog will
115 appear -- make sure "Copy items" is unchecked and "Reference Type" is "Relative to Project"
116 before clicking "Add".
117
118 2. Open the Three20 Xcode Project that you just added to your app and expand the "Dependencies"
119 group. Select all of the projects listed there and drag them to your app as well. You should
120 now have the following list of Three20 projects added to your app:
121 * Three20Core
122 * Three20Network
123 * Three20Style
124 * Three20UICommon
125 * Three20UINavigator
126 * Three20UI
127 * Three20
128
129 3. Link the Three20 static libraries to your project. Select all of the
130 project items that you just added to the sidebar.Under the "Details" table, you will see
131 a number of items, such as libThree20.a and libThree20Core.a. Check the checkbox on the
132 far right for each of the `lib` files (not the UnitTests). This will link each part of the
133 Three20 framework to your app.
134
135 4. Add Three20 as a dependency of your project, so Xcode compiles it whenever
136 you compile your project. Expand the "Targets" section of the sidebar and double-click your
137 application's target. Under the "General" tab you will see a "Direct Dependencies" section.
138 Click the "+" button, select "Three20" and each of the other libs, and click "Add Target".
139 You do *not* need to add the `UnitTests` target for each lib.
140
141 5. Add the bundle of images and strings to your app. Locate "Three20.bundle" under
142 "three20/src" and drag and drop it into your project. A dialog will appear -- make sure
143 "Create Folder References" is selected, "Copy items" is unchecked, and "Reference Type" is
144 "Relative to Project" before clicking "Add".
145
146 6. Add the Core Animation framework to your project. Right click on the
147 "Frameworks" group in your project (or equivalent) and select Add > Existing Frameworks.
148 Then locate QuartzCore.framework and add it to the project.
149
150 7. Finally, tell your project where to find the Three20 headers. Open your
151 "Project Settings" and go to the "Build" tab. Look for "Header Search Paths" and double-click
152 it. Add the relative path from your project's directory to the
153 "three20/Build/Products/three20" directory.
154
155 8. While you are in Project Settings, go to "Other Linker Flags" under the "Linker" section, and
156 add "-ObjC" to the list of flags. WARNING: Make sure that you do this for all configuration
157 settings, not just the active one.
7d34801 @jverkoey Add plenty of content.
jverkoey authored
158
afd5083 @jverkoey Flesh out the "Add Three20 to your project" article.
jverkoey authored
159 9. You're ready to go. Just #import "Three20/Three20.h" anywhere you want to use Three20 classes
160 in your project. It's recommended that you do so in a precompiled header for faster build times.
Something went wrong with that request. Please try again.