Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Doc: update docs/windows.rst #3825

Merged
merged 1 commit into from
Sep 28, 2023
Merged

Doc: update docs/windows.rst #3825

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 66 additions & 15 deletions docs/windows.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Microsoft Visual Studio
.............................................................................
https://www.visualstudio.com/

Obviously there is Microsoft Visual Studio 2013. Many professional developers targeting Windows use Visual Studio. Visual Studio comes in a couple of different editions. Their Express and Community editions are free to use, but a Microsoft-account is required to download the .iso and when you want to continue using it after a 30-days trial period. Other editions of Visual Studio must be purchased.
Many professional developers targeting Windows use Visual Studio. Visual Studio comes in a couple of different editions. Their Express and Community editions are free to use, but a Microsoft-account is required to download the .iso and when you want to continue using it after a 30-days trial period. Other editions of Visual Studio must be purchased.

Installing Visual Studio will give you the IDE, the command line compilers and the MS-version of make named nmake.

Expand Down Expand Up @@ -46,7 +46,48 @@ Building ctags from the command line
Microsoft Visual Studio
.............................................................................

Most users of Visual Studio will use the IDE and not the command line to compile a project. But by default a shortcut to the command prompt that sets the proper path is installed in the Start Menu. When this command prompt is used ``nmake -f mk_mvc.mak`` will compile ctags. You can also go into the ``win32`` subdirectory and run ``msbuild ctags_vs2013.sln`` for the default build. Use ``msbuild ctags_vs2013.sln /p:Configuration=Release`` to specifically build a release build. MSBuild is what the IDE uses internally and therefore will produce the same files as the IDE.
Microsoft Visual Studio provides ``Visual Studio Developer Command Prompt`` for command-line enthusiasts.

There are two ways to setup ``Visual Studio Developer Command Prompt``.

The first way to setup ``Visual Studio Developer Command Prompt`` is by clicking the ``Windows Start Menu``, details please refer to https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2019

The second way to setup ``Visual Studio Developer Command Prompt`` is opening ``Command Prompt`` Application and calling ``vcvarsall.bat`` in current ``Command Prompt``.

The location of ``vcvarsall.bat`` is various for different Microsoft Visual Studio versions and editions.

For Microsoft Visual Studio 2022 Enterprise::

C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat

For Microsoft Visual Studio 2022 Community::

C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat

For Microsoft Visual Studio 2019 Enterprise::

C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\VC\Auxiliary\Build\vcvarsall.bat

For Microsoft Visual Studio 2019 Community::

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat

Following is an example shows you how to use ``vcvarsall.bat`` to setup ``Visual Studio Developer Command Prompt``::

call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64

For more details about ``vcvarsall.bat`` please refer to https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160

Once ``Visual Studio Developer Command Prompt`` is setup, you can build ctags with ``NMake`` or ``MSBuild``.

Building ctags with NMake
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This requires Microsoft Visual Studio 2019 or later.

The simplest build instructions like below::

nmake -f mk_mvc.mak

If you want to build an iconv enabled version, you must specify ``WITH_ICONV=yes`` and ``ICONV_DIR`` like below::

Expand All @@ -60,29 +101,39 @@ If you want to create PDB files for debugging even for a release version, you mu

nmake -f mk_mvc.mak PDB=1

GCC
.............................................................................
Building ctags with MSBuild
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**General**
This supports only Microsoft Visual Studio 2013.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just tried with Microsoft Visual Studio Express 2017 and it seems that the project files for 2013 still works. (I haven't tried with 2019 or 2022 yet.)

I had to copy some files before running the msbuild command.

copy win32\config_mvc.h config.h
copy win32\gnulib_h\langinfo.h gnulib
copy win32\gnulib_h\fnmatch.h gnulib

Copy link
Member Author

@leleliu008 leleliu008 Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using VS2019 reported following:

C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\MSBuild\Microsoft\VC\v160\Microsoft.CppBuild.targets(439,5): error MSB8020: The build too 
ls for Visual Studio 2013 (Platform Toolset = 'v120') cannot be found. To build using the v120 build tools, please install Visual Studio 2013 build tools. 
  Alternatively, you may upgrade to the current Visual Studio tools by selecting the Project menu or right-click the solution, and then selecting "Retarge 
t solution". [C:\Users\vagrant\ctags\win32\ctags_vs2013.vcxproj]

I think the file name ctags_vs2013.* should rename to other name if it really supports VS2015 and VS2017.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, this PC has both VS2013 and VS2017 installed. So, even VS2017's msbuild is used, toolset from VS2013 is used.

If <PlatformToolset>v120</PlatformToolset> lines in the .vcxproj file are changed to <PlatformToolset>v141</PlatformToolset>, it might work on the newer VS versions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, currently, it is v120, we don't need to mention about other versions of VS now.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per https://learn.microsoft.com/en-us/cpp/build/how-to-modify-the-target-framework-and-platform-toolset?view=msvc-170#platform-toolset

Visual Studio 2010: v100
Visual Studio 2013: v120
Visual Studio 2015: v140
Visual Studio 2017: v141
Visual Studio 2019: v142
Visual Studio 2022: v143

PlatformToolset can't be changed via msbuild options.

It seems that we need ctags_vs2013.vcxproj ctags_vs2015.vcxproj ctags_vs2017.vcxproj ctags_vs2019.vcxproj ctags_vs2022.vcxproj.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that there is a way to support multiple versions of VS in one vcxporj file:
https://qiita.com/yumetodo/items/a8324efaf83c9c08d168 (Japanese)
The basic idea is to switch PlatformToolset based on VisualStudioVersion.
(This page suggests using CMake instead of this method, though.)

Copy link
Member Author

@leleliu008 leleliu008 Sep 21, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think we should use cmake instead of msbuild, we do not need to maintain nmake and msbuild build script, cmake build script is much easier than msbuild build script. moden Vistual Studio already includes the cmake as well.


All the GCC's come with installers or with zipped archives. Install or extract them in a directory without spaces.
Before starting to build, you need to copy somes file to proper location::

GNU Make builds for Win32 are available as well, and sometimes are included with the compilers. Make sure it is in your path, for instance by copying the make.exe in the bin directory of your compiler.
copy win32\config_mvc.h config.h
copy win32\gnulib_h\langinfo.h gnulib
copy win32\gnulib_h\fnmatch.h gnulib

Native win32 versions of the GNU/Linux commands cp, rm and mv can be useful. rm is almost always used in by the ``clean`` target of a makefile.
The simplest build instruction like below::

msbuild win32\ctags_vs2013.sln
k-takata marked this conversation as resolved.
Show resolved Hide resolved

**CMD**
If you want to build a release version, run command like below::

Any Windows includes a command prompt. Not the most advanced, but it is enough to do the build tasks. Make sure the path is set properly and ``make -f mk_mingw.mak`` should do the trick.
msbuild win32\ctags_vs2013.sln /p:Configuration=Release

If you want to build an iconv enabled version, you must specify ``WITH_ICONV=yes`` like below::
MSBuild is what the IDE uses internally and therefore will produce the same files as the IDE.

make -f mk_mingw.mak WITH_ICONV=yes
For more information about MSBuild, please refer to https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019

If you want to build a debug version, you must specify ``DEBUG=1`` like below::
GCC
.............................................................................

**General**

All the GCC's come with installers or with zipped archives. Install or extract them in a directory without spaces.

GNU Make builds for Win32 are available as well, and sometimes are included with the compilers. Make sure it is in your path, for instance by copying the make.exe in the bin directory of your compiler.

make -f mk_mingw.mak DEBUG=1
Native win32 versions of the GNU/Linux commands cp, rm and mv can be useful. rm is almost always used in by the ``clean`` target of a makefile.

**MSYS2**

Expand Down Expand Up @@ -146,7 +197,7 @@ All major distributions have both MinGW and MinGW-w64 packages. Cross-compiling
Building ctags with IDEs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

I have no idea how things work for most GNU/Linux developers, but most Windows developers are used to IDEs. Not many use a command prompt and running the debugger from the command line is not a thing a Windows developers would normally do. Many IDEs exist for Windows, I use the two below.
I have no idea how things work for the most GNU/Linux developers, but most of Windows developers prefer to use IDE over command prompt, running the debugger from the command line is not a thing a Windows developers would normally do. Many IDEs exist for Windows, I use the two below.

Microsoft Visual Studio
.............................................................................
Expand Down