flatpak.github.io/bundling-a-java-app.html at master · allanday/flatpak.github.io

History

248 lines (194 loc) · 19.7 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

<!DOCTYPE html>

<html>

<head>

<title>Flatpak</title>

</head>

<span class='sr-only'>Toggle navigation</span>

</button>

<a class="navbar-brand page-scroll" href="./">Flatpak</a>

</div>

<li>

<a href='index.html#about'>About</a>

</li>

<li>

<a class="page-scroll" href="getting.html">Getting Flatpak</a>

</li>

<li>

</li>

<li>

<a href='index.html#developers'>Build</a>

</li>

<li>

<a href='index.html#get-involved'>Get Involved</a>

</li>

<li>

</li>

</ul>

</div>

</nav>

</body>

<h1>Bundling a Java Application with Flatpak</h1>

<p>This tutorial will walk you through bundling a pre-built Java application using Flatpak. Many Java applications ship a pre-built tarball with the Java dependencies included, and this tutorial will step through an example of taking such a tarball and creating a Flatpak application from it.</p>

<p>To complete this tutorial, it is necessary to have flatpak and flatpak-builder installed on your system. See <a href="getting.html">getting Flatpak</a> for details on installing Flatpak on your system.</p>

<h2>Get the Application Tarball</h2>

<p>The application that we are going to bundle with Flatpak is Sweethome3D -- an application that lets you map a plan of the interior of your house so you can design and then view your design plans in 3D. Sweethome3D ships a prebuilt tarball that contains all the Java dependencies it requires, as well as the pre-built binary.</p>

<p>The first step is to download the Sweethome3D tarball, and extract it to your working directory:</p>

<pre>
<span class="unselectable">$ </span>wget http://downloads.sourceforge.net/project/sweethome3d/SweetHome3D/SweetHome3D-5.2/SweetHome3D-5.2-linux-x64.tgz
<span class="unselectable">$ </span>tar xvf SweetHome3D-5.2-linux-x64.tgz</pre>

<h2>Install the Flatpak Freedesktop SDK and runtime</h2>

<p>Every Flatpak application is required to specify a runtime that provides the core dependencies when the application is run. A Flatpak SDK is used just by you, the developer when building and bundling the application. See the <a href="developer.html">Developer page</a> for further details on how the runtimes and SDKs work.</p>

<p>For this example of bundling up Sweethome3D, we are going to use the Freedesktop SDK and runtime. The Freedesktop SDK and runtime are available in from the <a href="https://sdk.gnome.org/">GNOME SDK repository</a>. If you haven't previously set up this repository, you need to download the GPG key, then enable the repository:</p>

<pre>
<span class="unselectable">$ </span>wget https://sdk.gnome.org/keys/gnome-sdk.gpg
<span class="unselectable">$ </span>flatpak remote-add --gpg-import=gnome-sdk.gpg gnome https://sdk.gnome.org/repo/</pre>

<p>You now have enabled a new Flatpak repo called <code>gnome</code>. Next, install version 1.4 of the Freedesktop SDK and runtime from your newly enabled gnome repository:</p>

<pre>
<span class="unselectable">$ </span>flatpak install gnome org.freedesktop.Platform 1.4
<span class="unselectable">$ </span>flatpak install gnome org.freedesktop.Sdk 1.4</pre>

<h2>Create the Flatpak application</h2>

<p>Next up, we are going to create the Flatpak application that we are going to bundle Sweethome3D into. Use the following command to create the Flatpak application with the unique name <code>com.sweethome3d.App</code>, using the Freedesktop runtime and SDK:

<pre>
<span class="unselectable">$ </span>flatpak build-init sweethome3d-flatpak com.sweethome3d.App org.freedesktop.Sdk org.freedesktop.Platform 1.4</pre></p>

<p>This creates a default empty Flatpak application called <code>com.sweethome3d.App</code> in a new the directory <code>sweethome3d-flatpak</code>.</p>

<h2>Move the tarball contents into the Flatpak sandbox</h2>

<p>The <code>flatpak build</code> command lets you run commands within your newly created Flatpak sandbox. First we use <code>flatpak build</code> to create a <code>bin/</code> and a <code>SweetHome3D/</code> directory in the <code>/app/</code> directory within the sweethome3d-flatpak sandbox:</p>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak mkdir -p /app/SweetHome3D
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak mkdir -p /app/bin</pre>

<p>At this point, we can also run <code>ls</code> inside the build sandbox to see the results of the above two commands:</p>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak ls /app/</pre>

<p>Next, move the contents of the tarball we extracted in the '''Get the Application Tarball''' step above into the <code>/app/Sweethome3D/</code> directory in the sandbox:</p>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak cp -ra SweetHome3D-5.2/* /app/SweetHome3D</pre>

<p>Finally, make a sybmolic link for the Sweethome3D binary in <code>/app/SweetHome3D/SweetHome3D</code> to the <code>/app/bin/</code> directory in the sandbox.</p>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak ln -s /app/SweetHome3D/SweetHome3D /app/bin</pre>

<h2>Adding a Desktop entry, AppData, and an icon</h2>

<p>One thing you will notice about Sweethome3D is that the application does not ship a Desktop file, AppData file or application icon in the tarball. Including a desktop file will make the application show up in the menus of a Linux desktop, so a user can launch the application directly from their desktop environment (rather than having to run a terminal command). AppData files provide extra information about an application that Desktop environments can use to populate software installers (e.g. gnome-software and apper).</p>

<h3>creating and getting the files and icon</h3>

<p>Create a new file in your working directory called <code>com.sweethome3d.App.desktop</code> and populate it with a simple desktop entry for Sweethome3D:

<pre>
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=SweetHome 3D
Comment=Draw the plan of your home or office, test furniture layouts and view the results in 3D
Exec=SweetHome3D
Icon=com.sweethome3d.App.png
Terminal=false</pre></p>

<p>Next, create another new file called <code>com.sweethome3d.App.appdata.xml</code> in your working directory, and populate it with an AppData file for SweetHome3D:</p>

<pre>
<?xml version="1.0" encoding="UTF-8"?>

<component type="desktop">
 <id>com.sweethome3d.App.desktop</id>
 <metadata_license>CC0-1.0</metadata_license>
 <project_license>GPL-2.0</project_license>
 <name>SweetHome 3D</name>
 <summary>Draw the plan of your home or office, test furniture layouts and view the results in 3D</summary>
 <description>
 <p>
 Use SweetHome 3D to map out a plan of your house and plan the layout
 and colors of floors, walls and furniture.
 </p>
 <p>Example list:</p>
 <ul>
 <li>First item</li>
 <li>Second item</li>
 </ul>
 <p>
 This is another paragraph of information about SweetHome 3D and the Many
 things that you can use it for
 </p>
 </description>
 <screenshots>
 <screenshot type="default">
 <image>http://www.sweethome3d.com/images/gallery/SweetHome3DExample10-FlatWithMezzanine-VirtualVisit.jpg</image>
 <caption>The main window showing the application in action</caption>
 </screenshot>
 </screenshots>
 <url type="homepage">http://http://www.sweethome3d.com/</url>
</component></pre>

<p>The sweethome 3D tarball also does not ship with an icon included, so we need to download it from their upstream source control:</p>

<pre>
<span class="unselectable">$ </span>wget http://sweethome3d.cvs.sourceforge.net/viewvc/sweethome3d/SweetHome3D/src/com/eteks/sweethome3d/viewcontroller/resources/help/images/applicationIcon.png</pre>

<h3>Place them in the sandbox</h3>

<p>Now you have the 3 files in your working directory, we can place them in the appropriate locations in the build sandbox.</p>

<p>First, create the directory for the desktop file, and move the file from your working directory, to the build sandbox:</p>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak mkdir -p /app/share/applications/
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak cp com.sweethome3d.App.desktop /app/share/applications/</pre>

<p>Then do the same for the icon, being sure to rename it to <code>com.sweethome3d.App.png</code>

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak mkdir -p /app/share/icons/hicolor/128x128/apps/
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak cp applicationIcon.png /app/share/icons/hicolor/128x128/apps/com.sweethome3d.App.png</pre></p>

<p>Create the <code>/app/share/appdata/</code> directory in the sandbox, and copy the appdata file over:

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak mkdir -p /app/share/appdata/
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak cp com.sweethome3d.App.appdata.xml /app/share/appdata/</pre></p>

<p>After adding the AppData file, use the following command to generate the Appstream files:

<pre>
<span class="unselectable">$ </span>flatpak build sweethome3d-flatpak appstream-compose --prefix=/app --origin=flatpak --basename=com.sweethome3d.App com.sweethome3d.App</pre></p>

<p>This reads the desktop file, the icon and the appdata file and produces appstream files in <code>/app/share/app-info/</code>. Note that this step is done automatically if you are automating your build process with <a href="developer.html#Building_More_Complex_Apps_With_flatpak_builder">Flatpak-builder</a></p>

<h2>Finalize the build</h2>

<p>Next, we finalize the build of the Flatpak application. In this step, we tell Flatpak what the sandboxed application should have access to outside of the sandbox, and the name of the executable. In this Sweethome3D example, Sweethome3D needs access to the network, and to X11 (since it is a GUI application):</p>

<pre>
<span class="unselectable">$ </span>flatpak build-finish sweethome3d-flatpak --persist=.java --share=ipc --socket=x11 --share=network --command=SweetHome3D</pre>

<h2>Export the repo, and test out the application</h2>

<p>Your SweetHome3D Flatpak application is now complete. The next step is to export it into a local repository so we can install it and try it out. First, export the Flatpak application with:

<pre>
<span class="unselectable">$ </span>flatpak build-export repo sweethome3d-flatpak</pre>

This creates a <code>repo/</code> directory that contains your new repo with the SweetHome3D application in it.</p>

<p>Next, we need to add this to Flatpak as a "remote" repo, similar to what you did earlier for the SDK repo:

<pre>
<span class="unselectable">$ </span>flatpak --user remote-add --no-gpg-verify sweethome-repo repo</pre></p>

<p>Finally install the application from the newly linked repo, and run it:

<pre>
<span class="unselectable">$ </span>flatpak --user install sweethome-repo com.sweethome3d.App
<span class="unselectable">$ </span>flatpak run com.sweethome3d.App</pre></p>

<p>Also check the Application menus on your desktop environment, an entry for SweetHome 3D should now be visible in the menus, using the icon for SweetHome too.</p>

<h2>Automating this process with flatpak-builder</h2>

<p>The above steps have walked you through generating a Flatpak application using a series of manual steps. If you need to automate this process, there the <a href="developer.html#Building_More_Complex_Apps_With_flatpak_builder">Flatpak-builder</a> tool that lets you specify all the details of your Flatpak application, and will download and build the application automatically.</p>

<p>First, in a clean working directory from the steps above, create a new file called <code>com.sweethome3d.App.json</code> with the following contents:

<pre>
{
 "app-id": "com.sweethome3d.App",
 "runtime": "org.freedesktop.Platform",
 "runtime-version": "1.4",
 "sdk": "org.freedesktop.Sdk",
 "command": "SweetHome3D",
 "finish-args": [
 "--persist=.java",
 "--share=ipc", "--socket=x11",
 "--share=network"
 ],
 "modules": [
 {
 "name": "sweethome",
 "no-autogen": true,
 "sources" : [
 {
 "type": "archive",
 "url": "http://downloads.sourceforge.net/project/sweethome3d/SweetHome3D/SweetHome3D-5.2/SweetHome3D-5.2-linux-x64.tgz",
 "sha256": "c963afe9111e7b557cbdb99678926e5767c30928aa9565878f0d0b132151d69e"
 },
 {
 "type": "file",
 "path": "sweethome-Makefile",
 "dest-filename": "Makefile"
 }
 ]
 }
 ]
}</pre></p>

<p>You also need a simple Makefile to do the steps of placing the files in the tarball into the proper locations in the <code>/app/</code> directory in the sandbox. Create a new file called <code>sweethome-Makefile</code> and add the following contents:

<pre>
all:
 true
install:
 mkdir -p /app/SweetHome3D /app/bin
 cp -ra * /app/SweetHome3D
 ln -s /app/SweetHome3D/SweetHome3D /app/bin</pre></p>

<p>Now, with these two files created, running the following command will download the tarball, extract it, move the files into the correct locations, finalize the build, and export the repo:

<pre>
<span class="unselectable">$ </span>flatpak-builder --repo=repo sweethome3d-flatpak com.sweethome3d.App.json
<span class="unselectable">$ </span>flatpak run com.sweethome3d.App</pre></p>

<p>Finally, enable a the new repo as we did before, then install and run the application:

<pre>
<span class="unselectable">$ </span>flatpak --user remote-add --no-gpg-verify sweethome-repo2 repo
<span class="unselectable">$ </span>flatpak --user install sweethome-repo2 com.sweethome3d.App
<span class="unselectable">$ </span>flatpak run com.sweethome3d.App</pre></p>

</div></div></div></section>

</a>

</div>

</li>

<a class='page-scroll' href='index.html#about'>About</a>

</li>

<a class="page-scroll" href="getting.html">Getting Flatpak</a>

</li>

<ul>

<li>

</li>

</ul>

</li>

<a class='page-scroll' href='index.html#developers'>Build</a>

<ul>

<li>

<a class="page-scroll" href="developer.html">Getting Started with Flatpack</a>

</li>

<li>

<a class="page-scroll" href="bundling-a-java-app.html">Bundling a Java Application with Flatpak</a>

</li>

</ul>

</li>

<a class='page-scroll' href='index.html#get-involved'>Get Involved</a>

</li>

</li>

</ul>

</div>

</section>

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

ga('create', 'UA-68811788-1', 'auto');

ga('send', 'pageview');

</script>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

bundling-a-java-app.html

Latest commit

History

bundling-a-java-app.html

File metadata and controls