AppImage/en: Difference between revisions

From FreeCAD Documentation
(Updating to match new version of source page)
(Updating to match new version of source page)
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:
<languages/>
<languages/>

{{TOCright}}
{{TOCright}}
== What is an AppImage ==
[[Image:AppImage-logo.png|link=https://appimage.org]] ''Package once and run everywhere. Reach users on all major Linux desktop distributions.''


== What is an AppImage? ==
AppImage is a format similar to a binary that allow to quickly distribute an application to almost any Linux distro. Read more about it on the [https://appimage.org Appimage homepage] and [https://en.wikipedia.org/wiki/AppImage Wikipedia].

[[Image:AppImage-logo.png|link=https://appimage.org]] {{Emphasis|Package once and run everywhere. Reach users on all major Linux desktop distributions.}}

AppImage is a "universal binary package" intended to distribute an application to any Linux distribution. Read more about it on the [https://appimage.org Appimage homepage] and [https://en.wikipedia.org/wiki/AppImage Wikipedia].

To run it, first make it executable, and then type the relative or full path.

{{Code|code=
chmod +x FreeCAD_xxx-x86_64.AppImage
./FreeCAD_xxx-x86_64.AppImage
}}

For other types of installation see [[Download|Download]].


== FreeCAD AppImages ==
== FreeCAD AppImages ==


{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
=== Stable version ===
|+ style="text-align: center; font-size: 150%; | Available FreeCAD AppImages
Current stable version is [https://github.com/FreeCAD/FreeCAD/releases/download/{{:Template:Stable-Major-and-Minor-Version}}/FreeCAD_{{:Template:Stable-Version}}-Linux-Conda_Py3Qt5_glibc2.12-x86_64.AppImage FreeCAD_{{:Template:Stable-Version}}]
|+
! style="text-align: center; font-size: 200%;" | Stable
! style="text-align: center; font-size: 200%;" | Development
|-
| style="text-align: center;" | [[Image:AppImage-logo.png|link=https://github.com/FreeCAD/FreeCAD-Bundle/releases/tag/0.21.2]] [https://github.com/FreeCAD/FreeCAD-Bundle/releases/tag/0.21.2 v0.21.2]
| style="text-align: center;" | [[Image:AppImage-logo.png|link=https://github.com/FreeCAD/FreeCAD-Bundle/releases/tag/weekly-builds]] [https://github.com/FreeCAD/FreeCAD-Bundle/releases/tag/weekly-builds Weekly build]
|}


'''Important Notes:'''
=== Development version ===
* Development happens daily and rapidly.
Many users on the forum utilize the development version. It can be run on the same system in parallel with another version of FreeCAD. Users use the dev version to take advantage of the latest features and bug fixes (since FreeCAD has a long release cycle). They also use it to help test and find bugs to spur development and improvement of FreeCAD. For the most part the development version is stable but of course it's important to add the obligatory statement to use it at your own risk. Though most people 'save often' and are fine.
* Many users on the forum utilize the development version.
* It can be run on the same system in parallel with another version of FreeCAD.
* Users use the dev version to take advantage of the latest features and bug fixes (since FreeCAD has a long release cycle). They also use it to help test and find bugs to spur development and improvement of FreeCAD.


==== Obligatory Word of Caution ====
Current Development<sup>'''1,2'''</sup> version is [https://github.com/FreeCAD/FreeCAD/releases/download/0.19_pre/FreeCAD_{{:Template:Development-Version}}-Linux-Conda_Py3Qt5_glibc2.12-x86_64.AppImage FreeCAD_{{:Template:Development-Version}}]


For the most part the development version is stable but of course it's important to add the obligatory statement to use it at your own risk. Though most people that utilize backups and 'save often' do quite well.
'''Note<sup>1</sup>:''' Development happens daily and rapidly, the link for the most up-to-date AppImage is a moving target. <br />
'''Note<sup>2</sup>:''' The development link above should be up-to-date because it is updated via script.


== Automatic updating ==
Some methods to follow new developments:
* [[Appimage#Auto_Updating|Automatic updating]] requires downloading 3rd part AppImage software to do so
* Manually browsing https://github.com/FreeCAD/FreeCAD/releases/ and downloading the latest build
'''Note:''' At the time of this wiki edit there are 2 appimages being generated, one is a python3/Qt5 build and the other is a python2/Qt4 build. We recommend at this time to use the former and help the team weed out any py3/Qt5 bugs before the upcoming release of 0.18


AppImage has a smart and economical way of updating. It calculates the difference between the new AppImage and the old one, and will only download the changes between their versions. In theory the user ends up downloading around 15% each time instead of an entirely new AppImage.
== Auto Updating ==
AppImage has a very smart and economical way of updating. It calculates the delta between the new appimage and the older one and will only download the changes between their versions. So essentially, the user theoretically ends up downloading ~10%-15% instead of a new appimage each time. This is done via [https://github.com/AppImage/AppImageUpdate AppImageUpdate] application. There are two methodologies to update through, the 1) graphical interface (GUI) dialog box and 2) the command line (CLI) via a text terminal.


Automatic updating is done via several optional methods. Currently there are 4 methods, 2 through the graphical interface (GUI), and 2 through the command-line/terminal interface (CLI).
=== GUI ===
<ol>
<li>Download https://github.com/AppImage/AppImageUpdate/releases/download/continuous/AppImageUpdate-x86_64.AppImage
<li>Make it executable by right clicking on the file, going in to properties and 'Run as an executable'
<li>Click on the AppImage icon, a dialog box will appear and you'll be prompted to specify what AppImage you want to update
<li>Specify the path to your AppImage
<li>Once AppImage is updated, press the button named: <tt>Run updated AppImage</tt>
</ol>


=== CLI ===
=== Experimental in-app updating ===

$ wget https://github.com/AppImage/AppImageUpdate/releases/download/continuous/appimageupdatetool-x86_64.AppImage
Thanks to the efforts of several key devs, there is an [https://forum.freecadweb.org/viewtopic.php?f=8&t=44324 ongoing effort] to integrate a feature that allows '''self-updating the AppImage within FreeCAD''' itself. Starting from FC 0.19.21514 there now exists an AppImage section found via {{MenuCommand|Edit → Preferences → AppImage}}. Please test this capability and report your experience to the [https://forum.freecadweb.org/viewtopic.php?f=8&t=44324 forum discussion].
$ chmod +x ./appimageupdatetool-x86_64.AppImage

$ ./appimageupdatetool.AppImage path/to/old/FreeCAD.AppImage
=== GUI method 1 (official) ===
$ chmod +x path/to/updated/FreeCAD.AppImage

$ ./path/to/updated/FreeCAD.AppImage
This is the official AppImageUpdate GUI application.
Tips:
# Download [https://github.com/AppImage/AppImageUpdate/releases/download/continuous/AppImageUpdate-x86_64.AppImage AppImageUpdate-x86_64.AppImage].
# Make it executable by right clicking on the file, going in to properties and "Run as an executable".
# Double click on the AppImage icon, a dialog box will appear and you'll be prompted to specify what AppImage you want to update.
# Specify the path to your existing AppImage.
# Once the AppImage is updated, press the button {{Button|Run updated AppImage}}.

=== GUI method 2 (unofficial) ===

This is a sleeker 3rd-party unofficial version of AppImageUpdate named: '''AppImageUpdater'''. It is still in development (at the time of this wiki edit) but nevertheless, quite nice to use.
# Download [https://github.com/antony-jr/AppImageUpdater/releases/tag/continuous AppImageUpdater-*-x86_64.AppImage]
# Make it executable: {{Code|code=chmod +x AppImageUpdater*-x86_64.AppImage}}
# Run it: {{Code|code=source AppImageUpdater*-x86_64.AppImage}}
# Find your current FreeCAD AppImage and drag-drop it on to the AppImageUpdater
Result: Follow the AppImageUpdater prompts

=== CLI method 1 (official) ===

Run the following instructions in your terminal

{{Code|code=
wget https://github.com/AppImage/AppImageUpdate/releases/download/continuous/appimageupdatetool-x86_64.AppImage
chmod +x ./appimageupdatetool-x86_64.AppImage
./appimageupdatetool.AppImage path/to/old/FreeCAD.AppImage
chmod +x path/to/updated/FreeCAD.AppImage
./path/to/updated/FreeCAD.AppImage
}}

Notes:
* The file names will be unique because of the version info is embedded in them. The above instructions are simplified for convenience.
* The file names will be unique because of the version info is embedded in them. The above instructions are simplified for convenience.
* Run <tt>./appimageupdatetool-x86_64.AppImage --help</tt> to learn about functionality like <tt>-r</tt> and <tt>--self-update</tt>
* Run {{incode|./appimageupdatetool-x86_64.AppImage --help}} to learn about functionality like {{incode|--remove-old}}, {{incode|--overwrite}} and {{incode|--self-update}}.
* There is also an i386 version (see the [https://github.com/AppImage/AppImageUpdate/releases AppImageUpdate Release page])
* There is also an i386 version; see the [https://github.com/AppImage/AppImageUpdate/releases AppImageUpdate release] page.


Todo: share a script that can be added as an alias or cron job
Todo: share a script that can be added as an alias or [https://en.wikipedia.org/wiki/Cron cron] job.


=== CLI method 2 (unofficial) ===
== Using AppImages in your Development Workflow ==
'''Note:''' This section is specifically for developers


Similarly to the Graphical methods having an official and unofficial approaches to downloading AppImages, the same applies to the command line. This is a sleeker 3rd-party command line option to download AppImages.
A very convenient aspect of FreeCAD is that a majority of it is built in python and doesn't require to manually compile the code (like c++). Essentially, a python file can be modified and upon restarting FreeCAD those changes will be integrated. A developer can quickly work on the latest FreeCAD release using this technique and an appimage. FYI, mentioned procedure doesn't modify the environment in any way, that is nothing gets installed and no environment paths get modified. All one needs to do is the following:

# Download [https://github.com/antony-jr/AppImageUpdater/releases/tag/continuous-cli appimageupdater-*-x86_64.AppImage]
# Make it executable: {{Code|code=chmod +x appimageupdater*-x86_64.AppImage}}
# Run it: {{Code|code=source appimageupdater*-x86_64.AppImage /path/to/old/FreeCAD-AppImage.AppImage}}
'''Result''': Updates specified AppImage file if update exists


= Experimental =

== Fixing AppImage zsync ==

It may happen that an AppImage won't update because it's target file changed in some way. Instead of downloading a whole new AppImage, it's possible to rewrite the zsync file that is used by the AppImage to download the delta. More info can be found at https://github.com/antony-jr/appimage-update-info-writer.

This section needs more details.

== Downloading via Bittorrent ==

An experimental feature that the FreeCAD packaging team is exploring (thanks to the work of Antony-jr) is being able to download an appimage delta of FreeCAD via bittorrent. The repository issue is at https://github.com/FreeCAD/FreeCAD-Bundle/issues/49

= Developer Section =

{{Emphasis|Note:}} the following sections are intended for developers

== Unpacking AppImages ==

A very convenient aspect of FreeCAD is that a majority of it is built in [[Python|Python]], which doesn't need to be manually compiled like C++. Essentially, a Python file can be modified, and upon restarting FreeCAD those changes will be integrated into the application. A developer can quickly work on the latest FreeCAD release using this technique and an AppImage. Moreover, using an AppImage doesn't modify your system's environment in any way, that is, nothing is installed and no environmental variables are modified.


=== Modifying AppImages ===
=== Modifying AppImages ===


An AppImage embeds a file system in it with everything that is required to run the application. In order to modify it, the file system needs to be extracted.
$ <FreeCAD>.AppImage --appimage-extract

$ cd squashfs-root/
{{Code|code=
(Open your python file(s) in you favorite code editor and save)
./FreeCAD_xxx.AppImage --appimage-extract
$ ./AppRun
cd squashfs-root/
}}

Now open the required Python source files in your preferred code editor, modify them, and save them. Then run the application.

{{Code|code=
./AppRun
}}


=== Repackaging AppImages ===
=== Repackaging AppImages ===
If you've done the above and now want to re-package the AppImage with your latest changes proceed as follows:


If you've modified the code, and now want to re-package the AppImage with your latest changes, use the [https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage appimagetool-x86_64] tool on the extracted file system.
$ cd ..

$ wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage"
{{Code|code=
$ chmod a+x appimagetool-x86_64.AppImage
cd ..
$ ./appimagetool-x86_64.AppImage squashfs-root
wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage"
chmod +x appimagetool-x86_64.AppImage
./appimagetool-x86_64.AppImage squashfs-root
}}

== Personalized AppImages ==

Thanks to the work of {{Emphasis|realthunder}}, author of [[App_Link|App Link]] and [[Assembly3_Workbench|Assembly3 Workbench]], it is possible to build custom AppImages using a set of scripts.

This makes it very convenient to release images for a specific branch of the source code for others to test. Although AppImages only work on Linux, realthunder's scripts make it possible to generate AppImages also on Windows and MacOS.

The repository for these scripts is at [https://github.com/realthunder/FreeCADMakeImage realthunder/FreeCADMakeImage]. Please read the [https://github.com/realthunder/FreeCADMakeImage/blob/master/Readme.md Readme.md] for more details.

== Related ==

* [[Ubuntu_Snap|Snap]] packages.
* [[Flatpak|Flatpak]] packages.



[[Category:Administration]]
[[Category:Packaging{{#translation:}}]]
[[Category:Developer Documentation]]
[[Category:Developer Documentation{{#translation:}}]]
[[Category:Testing{{#translation:}}]]
{{Userdocnavi{{#translation:}}}}

Latest revision as of 05:37, 9 January 2024

What is an AppImage?

Package once and run everywhere. Reach users on all major Linux desktop distributions.

AppImage is a "universal binary package" intended to distribute an application to any Linux distribution. Read more about it on the Appimage homepage and Wikipedia.

To run it, first make it executable, and then type the relative or full path.

chmod +x FreeCAD_xxx-x86_64.AppImage
./FreeCAD_xxx-x86_64.AppImage

For other types of installation see Download.

FreeCAD AppImages

Available FreeCAD AppImages
Stable Development
v0.21.2 Weekly build

Important Notes:

  • Development happens daily and rapidly.
  • Many users on the forum utilize the development version.
  • It can be run on the same system in parallel with another version of FreeCAD.
  • Users use the dev version to take advantage of the latest features and bug fixes (since FreeCAD has a long release cycle). They also use it to help test and find bugs to spur development and improvement of FreeCAD.

Obligatory Word of Caution

For the most part the development version is stable but of course it's important to add the obligatory statement to use it at your own risk. Though most people that utilize backups and 'save often' do quite well.

Automatic updating

AppImage has a smart and economical way of updating. It calculates the difference between the new AppImage and the old one, and will only download the changes between their versions. In theory the user ends up downloading around 15% each time instead of an entirely new AppImage.

Automatic updating is done via several optional methods. Currently there are 4 methods, 2 through the graphical interface (GUI), and 2 through the command-line/terminal interface (CLI).

Experimental in-app updating

Thanks to the efforts of several key devs, there is an ongoing effort to integrate a feature that allows self-updating the AppImage within FreeCAD itself. Starting from FC 0.19.21514 there now exists an AppImage section found via Edit → Preferences → AppImage. Please test this capability and report your experience to the forum discussion.

GUI method 1 (official)

This is the official AppImageUpdate GUI application.

  1. Download AppImageUpdate-x86_64.AppImage.
  2. Make it executable by right clicking on the file, going in to properties and "Run as an executable".
  3. Double click on the AppImage icon, a dialog box will appear and you'll be prompted to specify what AppImage you want to update.
  4. Specify the path to your existing AppImage.
  5. Once the AppImage is updated, press the button Run updated AppImage.

GUI method 2 (unofficial)

This is a sleeker 3rd-party unofficial version of AppImageUpdate named: AppImageUpdater. It is still in development (at the time of this wiki edit) but nevertheless, quite nice to use.

  1. Download AppImageUpdater-*-x86_64.AppImage
  2. Make it executable:
    chmod +x AppImageUpdater*-x86_64.AppImage
    
  3. Run it:
    source AppImageUpdater*-x86_64.AppImage
    
  4. Find your current FreeCAD AppImage and drag-drop it on to the AppImageUpdater

Result: Follow the AppImageUpdater prompts

CLI method 1 (official)

Run the following instructions in your terminal

wget https://github.com/AppImage/AppImageUpdate/releases/download/continuous/appimageupdatetool-x86_64.AppImage
chmod +x ./appimageupdatetool-x86_64.AppImage
./appimageupdatetool.AppImage path/to/old/FreeCAD.AppImage
chmod +x path/to/updated/FreeCAD.AppImage
./path/to/updated/FreeCAD.AppImage

Notes:

  • The file names will be unique because of the version info is embedded in them. The above instructions are simplified for convenience.
  • Run ./appimageupdatetool-x86_64.AppImage --help to learn about functionality like --remove-old, --overwrite and --self-update.
  • There is also an i386 version; see the AppImageUpdate release page.

Todo: share a script that can be added as an alias or cron job.

CLI method 2 (unofficial)

Similarly to the Graphical methods having an official and unofficial approaches to downloading AppImages, the same applies to the command line. This is a sleeker 3rd-party command line option to download AppImages.

  1. Download appimageupdater-*-x86_64.AppImage
  2. Make it executable:
    chmod +x appimageupdater*-x86_64.AppImage
    
  3. Run it:
    source appimageupdater*-x86_64.AppImage /path/to/old/FreeCAD-AppImage.AppImage
    

Result: Updates specified AppImage file if update exists


Experimental

Fixing AppImage zsync

It may happen that an AppImage won't update because it's target file changed in some way. Instead of downloading a whole new AppImage, it's possible to rewrite the zsync file that is used by the AppImage to download the delta. More info can be found at https://github.com/antony-jr/appimage-update-info-writer.

This section needs more details.

Downloading via Bittorrent

An experimental feature that the FreeCAD packaging team is exploring (thanks to the work of Antony-jr) is being able to download an appimage delta of FreeCAD via bittorrent. The repository issue is at https://github.com/FreeCAD/FreeCAD-Bundle/issues/49

Developer Section

Note: the following sections are intended for developers

Unpacking AppImages

A very convenient aspect of FreeCAD is that a majority of it is built in Python, which doesn't need to be manually compiled like C++. Essentially, a Python file can be modified, and upon restarting FreeCAD those changes will be integrated into the application. A developer can quickly work on the latest FreeCAD release using this technique and an AppImage. Moreover, using an AppImage doesn't modify your system's environment in any way, that is, nothing is installed and no environmental variables are modified.

Modifying AppImages

An AppImage embeds a file system in it with everything that is required to run the application. In order to modify it, the file system needs to be extracted.

./FreeCAD_xxx.AppImage --appimage-extract
cd squashfs-root/

Now open the required Python source files in your preferred code editor, modify them, and save them. Then run the application.

./AppRun

Repackaging AppImages

If you've modified the code, and now want to re-package the AppImage with your latest changes, use the appimagetool-x86_64 tool on the extracted file system.

cd ..
wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage"
chmod +x appimagetool-x86_64.AppImage
./appimagetool-x86_64.AppImage squashfs-root

Personalized AppImages

Thanks to the work of realthunder, author of App Link and Assembly3 Workbench, it is possible to build custom AppImages using a set of scripts.

This makes it very convenient to release images for a specific branch of the source code for others to test. Although AppImages only work on Linux, realthunder's scripts make it possible to generate AppImages also on Windows and MacOS.

The repository for these scripts is at realthunder/FreeCADMakeImage. Please read the Readme.md for more details.

Related