Tutorial: Compiling G'MIC for Android Devices

[Mushy (Martin)]

G’MIC for the Android platform…

Although G’MIC has not been officially or extensively developed or tested on the Android platform, there are ways in which to get the command-line version, gmic cli, to work.
(Note: for Android version 7.0 and above)
The first way we could do it, would be to simply install the Termux terminal emulator (details below) and type:

pkg upgrade

followed by:

pkg install gmic

This will give you the latest available version of gmic as a command-line interface and you can then use it for image processing and the like to your heart’s content…

Except…

…certain users (well, just me as far as I know), have reported some filters are just not working at all, and some take longer to execute than expected; although the cause of these discrepancies hasn’t been definitively determined, it could be processor architecture or maybe application conflicts etc, but whatever it might be, having things randomly not work is a real pain…

So to attempt to resolve this issue I went about compiling G’MIC on an Android phone.

I wouldn’t class myself as an expert in the compilation process, so I was pleasantly surprised to be able to compile it myself (and to fix the initial problem) - if you are someone with little experience in this field too, don’t worry, it’s not (quite) as difficult as you might think… so, here we go!

Compiling gmic cli

In order to compile the G’MIC command-line interface (cli) on an Android device, try the following method:

If you haven’t done so already install F-Droid, this is a good place to download Termux (there are other ways which I shall come to, but there are other great applications at F-Droid, so why not…).

Download Option #1

Download the F-Droid APK file at https://f-droid.org - confirm the download and, tap on ‘Open’, choose the default ‘Open with Package installer’ or similar, or open it from your Downloads directory and take it from there if you prefer. Then tap on ‘Install’ and confirm that. Open the app, and once it has finished updating repositories, you can search using the Spy Glass icon bottom-right of the screen to search for Termux.

Download Option #2

Another way to get Termux is via the Github releases page here, as well as other methods, the thing to avoid is (sinister music plays) the Google Play Store, as the Termux version there is deprecated and could therefore be extremely problematic, so best to go with the latest from the above mentioned parties!

Okay, so download the Termux app and open it, you may be prompted by the operating system to give consent for privileged access and the like, do this (it’s perfectly safe) and continue to the Termux terminal, which is much like any standerd interface such as Windows command prompt or the Linux terminal, there will be displayed some helpful hints and messages, and you can get going.

A good way to learn the basics of Termux is to visit the wiki here Termux - Getting started.
So, best practice, as stated before type in to Termux:

pkg upgrade

Also, so Termux can “see” your filesystem and you can then access it, type:

termux-setup-storage

(You may need to exit the shell and then restart it for this to take effect)

Next up is Proot Distro, which is where the compiled version of gmic cli will exist.

(The reason being, in plain Termux there are no installation candidates for a lot of the software components needed to compile gmic cli - hence the need for the ‘terminal within a terminal’ if I may describe it as such, from the Github page it tells us a little bit more:
“…PRoot Distro is not a virtual machine. This is a container environment manager based on proot utility which is able to emulate chroot and mount --bind.”)
The following blog has a very useful guide to PRoot Distro, and gives many helpful proot-distro commands and tips on utilising it fully: Termux proot-distro usage: Install Linux distros on Android Phone · Ivon's Blog

So we need this in order to get ourselves a Linux distribution within our Termux environment, in order to utilise tools not available to the native Termux distribution, for our purposes I’ll be using Ubuntu.

So, in the Termux terminal, type or paste:

pkg install proot-distro

Once that is complete, we do:

proot-distro install ubuntu

(You can use pd instead of proot-distro)

If for some reason the package manager complains (it shouldn’t, but just in case), simply type:

pd install

…and you will be presented with a list of distros to choose from, find ‘ubuntu’ from the list (near the end as it’s in alphabetical order) and now copy the whole line such as: ubuntu:24.04 and paste it after the install command, so:

pd install ubuntu:24.04

When that completes, to enter the Ubuntu instance, type or paste:

proot-distro login ubuntu

As mentioned, you can alternatively use the alias pd, so it would be:
pd login ubuntu

and you should see:

root@localhost:~#

From there, get the latest base software, type:

apt update && apt dist-upgrade

You are now ready to compile G’MIC!

Okay first off the G’MIC webpage compilation guide states “First you need to install all the required tools and libraries:”, so to do that type or paste:

apt install git build-essential libgimp-3.0-dev libcurl4-openssl-dev libfftw3-dev libtiff-dev libjpeg-dev libopenexr-dev qtbase5-dev qttools5-dev-tools

This is slightly different from the recommendation on the download page as libgimp-3.0-dev is not mentioned, but libgimp2.0-dev is, however, recently this seems to have been pulled from the repos and seems not to be available, hence the need for the ..3.0.. version, luckily this works just fine (libgimp is the GIMP C API library used to build GIMP plug-ins/extensions, so I’m not sure if it’s absolutely necessary for a standalone instance of the gmic cli, but it’s best to be safe than sorry and include it anyway…!).

We don’t need to type ‘sudo’ because proot provides a way to simulate a root filesystem without actually needing root privileges on the host system. Which is nice.

Once completed get the G’MIC source, type/paste:

wget https://gmic.eu/files/source/gmic_3.7.6.tar.gz && tar zxvf gmic_3.7.6.tar.gz && cd gmic-3.7.6/src

Now to compile gmic, make sure your battery level is high enough, you don’t want it to power off, execute:

make cli

This will take quite a long time, so make a coffee (or tea), or do something less important (!), until it completes.
It should stop with the message:
strip gmic
And you should be able to type at the command-line now…

First of all you will need to link the gmic software to your terminal itself so it recognises the gmic command, so change directory, as you’re in the gmic source directory you should be able to get to the home directory by simply typing:

cd ../..

And type ls -a to make sure you are in the directory containing the .bashrc file, if not you can find it by typing:

find / -name .bashrc

Then you’ll need to edit it, type:

nano .bashrc

Press Enter and insert the following line (but remember to change the version number if different from this example):

export PATH="$PATH:$HOME/gmic-3.7.6/src"

Press ‘CTRL + o’ followed by Enter, to save the file, then ‘CTRL + x’ to exit nano.
Nearly there, type logout or exit - then simply log in again with:

pd login ubuntu

Before you do anything else you should update the filters with:

gmic up

… you can now use gmic command-line interface for FREE, I know it’s crazy right! (All donations welcome!). Hours of fun… Projects completed… Making people in photos look funny etc. Seriously though - it’s a powerful tool, and full respect and regards to all the devs, technicians, writers, testers, designers, artists and hobbyists who all contribute to and embrace this wonderful project!!! (Got a bit emotional there snif).

You now have the ability to process many formats of images (including 3D content etc) - JPEG, PNG, BMP, EXR, WEBP, TIFF, ORA and many more …

If you’re using a phone/tablet and don’t have access to a G’MIC gui and so can’t copy filter parameters easily, you might be a bit stuck, so as a quick (random) guide we could do:

gmic 640,640,1,3 Cercles_Concentriques_A 800,1,6,0,180,0,1,1,272,1,1,0,0,0,255,0,0,5,195,5,360,0,0,255,255,128,58,0,87,0,255,0,0,255,0,255,0,1,1,0,5,0,0,0,5,0,210,0 k[0] o circ-con00.jpg

gmic image.jpg repeat 3 smooth 40,0,1,1,2 done o output.jpg

gmic image.jpg rep_fx_shift 87,21,3,5,0 o shifted.jpg

gmic image.jpg fx_warp_perspective 1.5,0.6,1,8,70,0,50,3 o warped.jpg

gmic image.jpg fx_adjust_colors 0,18,8.5,-12,5.25,0,50,50 o new_coloured.jpg

You could even string all those filters together into one command:

gmic 640,640,1,3 Cercles_Concentriques_A 800,1,6,0,180,0,1,1,272,1,1,0,0,0,255,0,0,5,195,5,360,0,0,255,255,128,58,0,87,0,255,0,0,255,0,255,0,1,1,0,5,0,0,0,5,0,210,0 repeat 3 smooth 40,0,1,1,2 done rep_fx_shift 87,21,3,5,0 fx_warp_perspective 1.5,0.6,1,8,70,0,50,3 fx_adjust_colors 0,18,28.5,-17,5.25,0,50,50 k[0] o output-2.jpg

Why you would want to do that is anybody’s guess, but it goes to prove that the possibilities are (almost) endless!

If I want to peruse a filter’s parameters without access to a GUI, I can perhaps dig out some old scripts I put together, and modify them, or I could go to https://gmic.eu/update376.json - and look at how to construct the parameters of any filter I wish - it can be a tricky and time consuming process, but it can also prove fruitful.
List of gmic commands may help too for some easier copy/pasting.

TROUBLESHOOTING:

If compiling for some reason doesn’t work, it might not be obvious why that is, you may get an error like:

compilation terminated due to -Wfatal-errors ...

Or it could be something entirely different, but I have found a way which could help:

Execute the following command:

lscpu | egrep 'Model name|Architecture|Vendor ID|CPU family|Model|Stepping'

This will proceed to list various information, but what we need to find out is what the: Model name line(s) tells us, in my case it was cortex-a75, although it also displayed cortex-a55 but I chose the former as it’s the faster processor. Yours may well be different.

Keep a note of it as you will need it soon - and it’s on to the next step, editing the Makefile.

As you should still be in the gmic source directory, now type:

nano Makefile

This brings up our gmic Makefile in the nano editor (other editors are available if you prefer!), use the search function by pressing ‘CTRL + w’, type:

-mtune=generic

press Enter, you will see the parts (two entries) to edit, replace them with the value you obtained. In my case that was ‘cortex-a75’.

Before:

After:

Now press ‘CTRL + o’ follwed by Enter, to save the file, then ‘CTRL + x’ to exit nano.
With the Makefile edited it’s now time to compile gmic cli.

This could take a long time, so remember, make sure your battey level is high enough, you don’t want it to power off mid- way through!

We will need to use certain flags that are specifically used for older gcc versions, however, this seems to work also for Android devices for whatever reason, and I’m not guessing because I’d probably be wrong let’s face it, all I know is, it works, so the command to use is:

make cli OPENMP_CFLAGS="" OPENMP_LIBS=""

Have fun!

[prawnsushi]

Thanks for taking the time to write this tutorial
Funny enough, on a macbook air, mtune is empty. Might be normal though?

@Mushy

If you’re using a phone/tablet and don’t have access to a G’MIC gui and so can’t copy filter parameters easily,

You can also use G’mic Online to copy the filters’ params.

[grosgood (Garry R. Osgood)]

@Mushy

editing the Makefile.

Yes, I suggested it, but it is not best practice. Better practice is to override symbols originally defined in the Makefile itself with command line over-rides; in this regime, do not edit the Makefile.

In particular, override the symbol for cc optimization flags: OPT_CFLAGS, so your make command discards the previous definition (in the Makefile) and replaces it with that found on the command line. In accordance with this example:

make cli OPENMP_CFLAGS="" OPENMP_LIBS="" OPT_CFLAGS="-03 -mtune=cortex-a55"

@Mushy

A slightly long-winded (but necessary)

Perhaps smarter than my first example in 3.4.0 filters issue… Post #9 would be:

$ gcc -c -Q -march=native -mtune=native --help=target | sed 's/[[:space:]]*//g' | grep -E 'march=|mtune='
-march=znver4
-mtune=znver4
Knownvalidargumentsfor-march=option:
Knownvalidargumentsfor-mtune=option:

(znver4 is peculiar to AMD processors, here an AMD Ryzen 9 7950X3D.)
That is, first pipe to the stream editor (sed) to remove all white space (as defined by your language locale); this minimizes the possibility of line wrapping on narrow Android phone displays. Then the output of the white-space-stripped stream is piped to the pattern matcher, which finds only those lines with either march= or mtune= patterns. This should dramatically cut down on the volume of text one has to search through.

Commonly, -march and -mtune appear together but sometimes -mtune is omitted. -march chooses an Instruction Set Architecture (ISA). Choosing an ISA does not induce the compiler to actually optimize the resulting assembly language in an ISA-specific way. that is what -mtune asks for. It is a bit unusual to specify -mtune without also explicitly choosing -march. To illustrate:

gosgood@bertha ~ $ gcc -c -Q -mtune=native --help=target | sed 's/[[:space:]]*//g' | grep -E 'march=|mtune=' 
-march=x86-64
-mtune=znver4
Knownvalidargumentsfor-march=option:
Knownvalidargumentsfor-mtune=option:

If I were to use only a -mtune=znver4 compiler option, then the ISA in play, x86-64, would only include the most common assembly language instructions of Intel / AMD processors, for which I am asking for optimizations for a Ryzen 9 7950X3D processor — but I have excluded the assembly language instructions specific to the 7950X3D processor, so my optimizations are probably not going to be very optimal. In light of that, you probably would want to amend your tutorial to include both -march and -mtune switches.

There will be those out there who couldn’t be arsed for searching through anything. For those folk, there could be this command line:

make cli OPENMP_CFLAGS="" OPENMP_LIBS="" OPT_CFLAGS="-03 -march=native -mtune=native"

which means ‘pick my ISA for me, (I don’t really want to know what it is) and optimize the assembly language instructions for it, (whatever that may be).’ They wouldn’t make use of $ gcc -c -Q -mtune=native --help=target… at all and avoid trying to make sense of its output.

That could be quicker, but if errors like this crops up:

x86_64-pc-linux-gnu-g++: error: 03: linker input file not found: No such file or directory

then a more deliberative and careful setting of -march and -mtune is called for, and the fellow looking for a fast get-a-way will have to look these up through gcc -c -Q -march=native -mtune=native --help=target output.

[Mushy (Martin)]

Oops, didn’t mean to besmirch the sacred Makefile! I shall repent…
Seriously though, I had attempted to change the -march entr(y)(ies) to -march=armv7-a+fp
… but if I recall the output suggested something untoward… so that’s why I decided on just the -mtune entries to modify. Also I tried changing the values to ‘native’ but the compiler didn’t want to know…
Anyway, food for thought, appreciate it!

EDIT:
Oddly, the gcc query:

gcc -c -Q -mtune=native --help=target | sed 's/[[:space:]]*//g' | grep -E 'march=|mtune='

produces a truncated result for me still, i.e.:

-march=armv7-a+fp
-mtune=cortex- 

[grosgood (Garry R. Osgood)]

At the end of the day, it works for you, and probably works for a bunch more. That is good. Thanks again for posting!

[Reptorian]

For any one that can edit the first post, including @Mushy . What I had to do is

pkg remove game-repo
pkg remove science-repo
pkg update (?)

To be able to get the very first step to work. So, I’d like to see this instruction added to first post. Not sure if pkg update is needed.

[Mushy (Martin)]

Which terminal are you using if you don’t mind me asking?

[Mushy (Martin)]

Yes, I’ve been thinking of re-writing it as it’s a bit clunky, I don’t know what where pkg update comes from although it’s obviously valid, but pkg upgrade is advisable, and one in your Ubuntu environment maybe do:

apt update && apt dist-upgrade

…did you compile gmic or install via package manager?
This tutorial is really a work in progress… I’m using Deepin instead of Ubuntu now (via proot-distro). No idea why I chose that, but it’s a good enough option.

[Reptorian]

Termux. Compile gmic.

[Mushy (Martin)]

And where did you download it from, either F-Droid or the GitHub releases page (.APK file) are the places to get Termux from. Hopefully you didn’t get it from the Play Store, as that is an older version, that will be problematic.

[Reptorian]

I did get it from Play Store or maybe it came with it, but updating it should not be a problem.

[Mushy (Martin)]

Ok, well this may be pertinent, from https://www.xda-developers.com/termux-terminal-linux-google-play-updates-stopped/ :
The Termux development team now wants users on the Play Store release to migrate to the F-Droid variant to continue getting updates. The migration process isn’t exactly straightforward because the builds are signed with a different set of keys, hence a seamless update can’t be performed…

[Reptorian]

I’m leaving a tip. I highly recommend that one do symbolic link to .gmic file on sd card.

1. Execute - termux-setup-storage
2. Drop .gmic file somewhere on your Android device.
3. While on ~ under proot-distro, execute ln -s target_file_location .gmic

There, no need to use nano.

Warning: Remove .gmic file under root folder before proceeding!

[Reptorian]

Another tip again. In your .gmic file, add command ps with code e ${}. Just so that you do not need to use {} characters.

[Reptorian]

Since you are here, maybe a script would be nice? To update and to use a linked .gmic file. I use linked .gmic because nano sucks.

[Mushy (Martin)]

@Reptorian Apologies for not replying all that time ago, tbh not sure what you mean about the .gmic file and how it ties in with the subject exactly…?
I’m definitely not an expert in coding or software development.

This tutorial is coming from a novice, and as such probably contains things which may not be accurate or best practice etc, but hopefully, as it describes my experiences compiling gmic for an Android system and it seems to work, hopefully it will help anyone trying to do the same.

I took on board the “Execute - termux-setup-storage” tip you mentioned, yes, that’s quite important, thanks. And the whole tutorial has been updated and modified somewhat!

Cheers!