-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rewritten Cairo and pngquant installation instructions for Windows #7163
Conversation
Thanks for the PR! I can't review this, my house has no Windows. @alexvoss? |
@squidfunk just a suggestion, there's an official Windows virtual machine that you can use for free, but it is time-limited to approximately 3 months. |
I will test it once back home. Got a Win 11 VM and a Win 10 laptop, so some diversity. |
``` | ||
|
||
and the libraries are in the `<INSTALL-DIR>\lib` directory. Use the debug | ||
script below to check if the path is included. If it isn't then: | ||
Use the debug script below to check if the path is included. If it isn't then: | ||
|
||
1. Press ++windows+r++. | ||
2. Run the `SystemPropertiesAdvanced` applet. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are libs installed via pacman available outside of the MSYS2 terminal?
Also if they are available, then some path is added to the PATH variable, are those instructions below still accurate?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shared libraries are in \bin
directory, which is noted in the changed lines just above this one; \lib
directory contains only static libraries, which should not be in PATH
, as far as I understand.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So the 4th point in list should point to the bin
and not lib
directory, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch. Let me clear that up.
Can I make a suggestion - if only so someone can shoot it down? We should make WSL, Docker (which is also WSL), and MSYS2 the three officially supported ways of getting the MSYS2 is for all those poor souls who cannot get WSL in their corporate environment, or those who actually like to work in Powershell. Installation is pretty easy to describe for us as we can rely on the installation process of MSYS2 and simply provide the The installation instructions for Whatcha think? |
Yes. To be fair, MinGW(-w64) is just one of the provided environments in MSYS2, but it is likely the most commonly used one. We can choose one of the other environments as well if it works well. Regarding pngquant, there is a package for it in MSYS2 too: https://packages.msys2.org/package/mingw-w64-x86_64-pngquant?repo=mingw64
Sounds good to me. |
Reading this StackOverflow post, it seems the difference is between UCRT64 and MINGW64 is that the latter supports version of Windows older than 10? We could see if UCRT64 works. Since it is the default shell for a new installation, it might be good to go with it? |
I have installed both libraries in UCRT64 and that worked fine. Unless we want to support Windows versions < 10, I would say making UCRT64 the default seems to be the way to go. It is a bit of a pain that pacman needs the precise package name including the specification of the environment, so the prefix would be |
MSYS2 anyhow requires Windows 10 64-bit or newer, so I agree.
I tested it independently in WinDev VM and confirmed it works as well. Current state of the pull request uses Pacman directly, but I can also rewrite it to use Pacboy. |
That is also fine with me. I don't think it is here or there whether you add an extra install to then install Cairo and Are you going to work on a new version along these lines? I am traveling tomorrow, so will be offline but happy to look at anything once I am back connected. Will be shlepping the Windows laptop with me. |
I don't know, I'm personally not a fan of Docker or WSL. I once installed it and the virtualization in my system changed and broke all of my VMware/VirtualBox VMs, as in, they wouldn't boot anymore. I didn't have any data on them, so I let it slide, but overall I consider Docker being too "invasive". Perhaps I just have a different ideology, as I prefer installing things manually instead of using reusable images. However, I do realize this is the standard nowadays, for developers. Now would Docker and WSL be another hurdle or would they actually simplify things, for the generic user, non-developer, which probably installed Python through the Microsoft Store (instead of doing it the "proper" manual way via the installer executable from the Python website)? 🤔 MkDocs does require running a Terminal command, and therefore by default we require a basic willingness to use the Terminal. However, I believe that most Windows users are used to clicking stuff, like the GTK Runtime installer, or modifying PATH via the window applet. I feel like MSYS2 is a good middle-ground between pure Windows and WSL as it adds direct options for installing libraries, without the need for a new system in a VM. However, it increases the amount of commands the user has to write to configure their setup, so it's difficult to outright say it will be better for the typical Windows non-developer. |
Honestly, I would prefer 2 commands instead of 3. Users who are familar with MSYS2 will understand the broad idea and know how to use Pacboy themselves. I would keep it as is.
I see where you are coming from and installers are indeed nice. On the other hand, I think we should recommend maintained packages (like those in MSYS2) over some builds for Windows made by some enthusiasts in 2022 and not kept up to date with upstream software development afterwards (which is better than not having them at all, of course, and I respect that). |
Instead of installing GTK+ and installing from source, suggested installing MSYS2 and obtaining Cairo built for UCRT64 via its Pacman.
@kamilkrzyskow my suggestion was based on the assumption that they are options already in use by many people who are technically-minded but work in a Windows shop. Docker is based on WSL, so should not get in the way of anything happening on the Windows side of things? Correct me if I am mistaken. MSYS2 is an alternative for those who cannot use WSL or are used to Powershell. It replaces installing GTK for Cairo. Note that the installation instructions currently linked to mention installing GTK via MSYS2, so not much gained there. The GTK runtime pointed to is also based on MSYS2, except the result has been bundled up in an installer. Some may well prefer that. For pngquant, the effective instructions are to compile it yourself, presumably using MSYS2, so just using |
True, cairo has a newer version
Your assumption might be correct, I've seen various non-developers (on GitHub issues/discussions) that still use Docker due to the simplicity of running prepared dockerfiles, I can see myself being the outlier with an odd perspective 😅 Depending on the system, enabling WSL with Docker might not be the easiest thing to do (as virtualization might be disabled in the BIOS), so I wouldn't consider WSL as the best candidate for "official" ways to do things, in the context of easy and simple static site generation.
Yes, as far as I know Docker runs on top of WSL2 with Hyper-V, but I'm not sure what you meant with the "get in the way" or "Windows side of things". Containers are similar to a sandbox environment, the point of them is to isolate software, so I would assume nothing should conflict with them, apart from other virtualization solutions that don't use Hyper-V (this happened in my case). |
Is this not taken care of with "if you are using WSL"? True, I would not want to write instructions for every BIOS on the plant for enabling virtualization (though this might one day become my own personal circle of hell, who knows). I mentioned Docker because that particular boat has sailed since it is mentioned in the installation guide. I personally also never understood the allure of Docker for something like this but people have different views on such matters. For me, the main question is more about how easy or simple the instructions are once you have chosen and prepared a deployment option. I would assume that someone who is happy to use WSL will also be able to make it run on their machine. Conflicting hypervisors is an unfortunate reality, are not new and not unique to Windows. |
Please let me know if I can make further improvements to the wording of the changes. For what its worth, while preparing a recent "build your own website with MkDocs" workshop, I found out there is now a PowerToys utilty for configuring Environment Variables. It could be a modern replacement for the current one that will eventually make it to official Windows via a future update. While it looks far nicer than the Windows built-in one, I would for the time being stick with the one that everyone has installed. |
Once @alexvoss finds some time to review this, I'm happy to merge it |
Wording is fine by me, also Alex has tested the MSYS2 installation.
I'm for sticking to the old Windows XP applet approach until the end of life for Windows 10 aka 2028 🤓 |
Perfect, thanks! LGTM. I didn't mention Pacboy (no idea what that is), @vedranmiletic did.
Sounds sensible. |
@vedranmiletic @kamilkrzyskow are you both using the Python from MSYS2? The one case that is not covered, was far as I can see, is where people install Python from python.org before they come across MSYS2. In that case they will use the recently introduced CAIROCFFI_DLL_DIRECTORIES environment variable or need to make sure they are always using the version from MSYS2, which would likely be the case within an MSYS2 environment but not in a Powershell. |
Uh oh, did I jump the gun again 👀 💦
Yes, I was answering to Vedran, but didn't adjust my message after you posted yours Martin, so the ordering did not work out 😅
I'm using Python installed from python.org, but I'm also not using MSYS2/Powershell directly. I'm using Git for Windows, which added Bash, and Git Bash is basically a Terminal like |
@kamilkrzyskow, am I reading your message right that in the end you are using a MingW64 version of Python? My experience with Python 3.12 from python.org is that I do need to set that extra environment variable. When I use Python from a MingW64 environment (MSYS2 in my case), I do not need this. My understanding is that this is because a MingW64 Python is compiled as if for a Unix-type environment and so does not contain the security patch that keeps the Windows version from searching in the PATH. This understanding seems consistent with the cairocffi documentation. |
I'm not sure, as it doesn't say GCC/MINGW64, which is what I would expect: sys.version
3.12.0 (tags/v3.12.0:0fb18b0, Oct 2 2023, 13:03:39) [MSC v.1935 64 bit (AMD64)] I can test MSYS2 on my machine if it's necessary to get to the bottom of this 🤔 |
For comparison, this is what I get in Powershell:
Could it be that the difference is that Python is installed under my account? |
This is what I get in PowerShell: PS C:\Users\HRY> gcm python
CommandType Name Version Source
----------- ---- ------- ------
Application python.exe 3.12.15... C:\MyFiles\Python312\python.exe
PS C:\Users\HRY> python
Python 3.12.0 (tags/v3.12.0:0fb18b0, Oct 2 2023, 13:03:39) [MSC v.1935 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information. You have version 0.0.0.0 of Python 3.12.3 and I have version 3.12.15... of Python 3.12.0 😆 The security permissions are default: My user-Path looks like this: My system-Path looks like this: EDIT: Another test with $PATH printing inside of the Git Bash terminal: (PythonVENV)
HRY@hry2060 MINGW64 ~
$ echo "${PATH//:/$'\n'}"
/c/MyFiles/PythonVENV/Scripts
/c/Users/HRY/bin
/mingw64/bin
/usr/local/bin
/usr/bin
/bin
/mingw64/bin
/usr/bin
/c/Users/HRY/bin
/c/Program Files/Eclipse Adoptium/jdk-19.0.1.10-hotspot/bin
/c/Program Files (x86)/VMware/VMware Player/bin
/c/windows/system32
/c/windows
/c/windows/system32/wbem
/c/windows/system32/windowspowershell/v1.0
/c/windows/system32/openssh
/c/program files/git/cmd
/c/program files/microsoft sql server/130/tools/binn
/c/program files/microsoft sql server/client sdk/odbc/170/tools/binn
/c/program files/process lasso
/c/program files (x86)/microsoft sql server/150/tools/binn
/c/program files/microsoft sql server/150/tools/binn
/c/program files/microsoft sql server/150/dts/binn
/c/program files (x86)/calibre2
/c/Program Files (x86)/NVIDIA Corporation/PhysX/Common
/c/Program Files/dotnet
/c/Users/HRY/3D Objects
/c/Program Files/Docker/Docker/resources/bin
/c/Program Files/GTK3-Runtime Win64/lib
/cmd
/c/ProgramData/chocolatey/bin
/c/MyFiles/Python312/Scripts
/c/MyFiles/Python312
/c/MyFiles/Python311/Scripts
/c/MyFiles/Python311
/c/MyFiles/Python310/Scripts
/c/MyFiles/Python310
/c/MyFiles/Python39/Scripts
/c/MyFiles/Python39
/c/MyFiles/Python38/Scripts
/c/MyFiles/Python38
/c/MyFiles/Python27/Scripts
/c/MyFiles/Python27
/c/MyFiles/Ruby31-x64/bin
/c/Users/HRY/AppData/Local/Microsoft/WindowsApps
/c/MyFiles/platform-tools
/c/MyFiles/mingw_8/mingw64/bin
/c/Users/HRY/.dotnet/tools
/c/Program Files/CMake/bin
/c/Users/HRY/3D Objects
/c/Users/HRY/AppData/Local/Programs/VSCodium/bin
/c/Users/HRY/AppData/Local/JetBrains/Toolbox/scripts
/c/MyFiles/NodeJS
/usr/bin/vendor_perl
/usr/bin/core_perl |
So, I suspected that the fact I had you have the DLL in the System path as opposed to the user path was the crucial difference but it did not make any difference on my system. The odd thing is that we are trying to find out why it works on your system rather than why it does not on mine. Gotta go and get my daughter from school. I suggest we leave it be until I find new information or someone else gets in touch who can help. |
From my experience with Python 3.11 installed in MSYS2, it just works without that variable. On the workshop we used Python 3.12, but did not build social cards, so I can't say. (That's my primary driver here: I want to show how good the social card look and how easy they are to build when we have that workshop again in a few months). |
Instead of installing GTK+ and installing from source, suggested
installing MSYS2 and obtaining Cairo built for UCRT64 via its Pacman.