Agar


<-- Back to Documentation

Installing Agar on Windows / Visual Studio (Updated)

This is a step-by-step guide for compiling Agar applications under Microsoft Visual Studio 6.0, 2002, 2003, 2005, 2008 and 2010. This guide also describes how to compile Agar itself, as well as the optional third-party libraries such as FreeType and Pthreads.

It is assumed that you already have the basic Microsoft Windows SDK ("Platform SDK") installed. The Visual C++ 2010 Redistributable Package is also required.

General Visual Studio Issues

Adding Include and Library paths to Visual Studio

Using external libraries from Visual Studio requires that the explicit Include and Library paths be specified. In all Visual Studio versions prior to 2010, you can add a directory to the Include or Library path from Tools / Options, then Projects and Solutions / VC++ Directories. In the "Show directories for" field, select the option "Include files" or "Library files" and add the new directory path to this list.

Starting from Visual Studio 2010, Library/Includes paths are handled differently. The Projects and Solutions / VC++ Directories dialog is no longer available, and Library/Include paths can be set on a per-project basis (i.e., right-click on the project node and select Properties / VC++ Directories). See this article for details.

It is still possible to specify global Include/Library paths by manually editing the Microsoft.Cpp.*.user.props files (found under AppData\Microsoft\MSBuild\v4.0 relative to your Local Settings\ or C:\Users\%USERNAME%\). Open this file in a text editor, and append your directories to $(IncludePath) and $(LibraryPath) like so:

    <PropertyGroup>
      <IncludePath>$(IncludePath);C:\Program Files\Agar\include</IncludePath>
      <LibraryPath>$(LibraryPath);C:\Program Files\Agar\lib</LibraryPath>
    </PropertyGroup>
  

Disabling Parallel Builds

As of Visual Studio 2010, parallel builds are enabled by default, even though the feature is buggy. If you are getting random build errors (e.g., some files cannot be opened even though they exist), make sure to disable parallel builds. To disable parallel builds, go to Tools / Options / Project and Solutions / Build and Run, and set "maximum number of parallel project builds" to "1".

Installing Agar

Get the latest Agar Windows binary package from the Agar download page. Standard Agar builds (FreeType + threads + OpenGL support) are strongly recommended, but Agar can still be compiled without FreeType, threads or OpenGL support.

Unpack the package to its target location such as C:\ProgramFiles\Agar.

Start Visual Studio and bring up Tools / Options. Select Projects and Solutions / VC++ Directories. In the "Show directories for" field, select the option "Include files".

Assuming you have unpacked the Agar binary package into C:\ProgramFiles\Agar, add C:\ProgramFiles\Agar\include and C:\ProgramFiles\Agar\lib to your VS Include/Library Paths.

Optional: SDL 1.x support

Note: If you are using a --without-sdl compilation profile, you can skip this section (see Generating a custom Agar compilation profile).

If you would like to use the "sdlgl" and "sdlfb" Agar drivers, the SDL 1.x development package must be installed. If you have not already installed SDL, go to the SDL download area, download the file SDL-devel-1.*-VC.zip and unpack its contents into a location such as C:\ProgramFiles\SDL.

Add C:\ProgramFiles\SDL\include and and C:\ProgramFiles\SDL\lib\x86 (or C:\ProgramFiles\SDL\lib\x64) to your VS Include/Library Paths.

Copy x86\SDL.dll to C:\Windows\System (or C:\Windows\System32 on x64), and x64\SDL.dll to C:\Windows\SysWOW64.

Optional: Multithreading support

Note: If you are using a --disable-threads compilation profile, you can skip this section (see Generating a custom Agar compilation profile).

Thread safety and support for thread management in Agar-Core requires the POSIX threads API. POSIX threads are supported natively by all modern, decent operating systems. But under Windows, you will need to install a small library called Pthreads-win32.

Go to the Pthreads-win32 download area, fetch the latest version (pthreads-w32-2-x-x-release.zip) and extract to in some temporary location. Move (and rename) the Pre-built.2 directory over to C:\ProgramFiles\Pthreads.

Copy the contents of the dll\x86 directory to your C:\Windows\System (or C:\Windows\System32 on x64), and the contents of dll\x64 to your C:\Windows\SysWOW64.

Add C:\ProgramFiles\Pthreads\include and C:\ProgramFiles\Pthreads\lib\x86 (or C:\ProgramFiles\Pthreads\lib\x64) to your VS Include/Library Paths.

Optional: FreeType font engine (recommended)

Note: If you are using a --without-freetype compilation profile, you can skip this section (see Generating a custom Agar compilation profile).

FreeType is the preferred font engine for Agar (the alternative is a monospace ASCII font only suitable for testing purposes). Like Pthreads, FreeType comes standard on decent operating systems, but under Windows, you have to install it manually.

Installing a precompiled FreeType

The following precompiled FreeType binary packages are available: FreeType 2.3.5 (VS2005 / x86), FreeType 2.4.12 (VS2010 / x86).

To install a FreeType binary package, unpack the archive into a directory such as C:\ProgramFiles\FreeType. Add C:\ProgramFiles\FreeType\include and C:\ProgramFiles\FreeType\lib to your VS Include/Library Paths.

Note that our precompiled packages may not work on your particular system. They were tested with Windows XP (Visual Studio 2005) and Windows 7 (Visual Studio 2010). If your Agar application fails to start, try compiling FreeType yourself instead.

Compiling FreeType yourself

FreeType provides a project file, so the build process is simple. Go to the FreeType2 download area, download the latest source package (ft*.zip), and unpack it to some temporary location.

In the FreeType sources, go to the builds\win32\vc* directory for your version of Visual Studio and open freetype.sln. Locate the Solution Configurations combo box in the Visual Studio toolbar, and select "Release Multithreaded".

Now build the solution. This will generate the static .lib file. Then, right-click on the freetype project entry in Solution Explorer, go to Properties and locate Configuration Properties / General. In the Project Defaults section, set the "Configuration Type" field to "Dynamic Library" (.dll), and build the solution again to generate the .dll version.

Exit Visual Studio, and go to the build directory (e.g., \objs\win32\vc2010) Locate the .lib and .dll files and install them into your C:\ProgramFiles\FreeType\lib, renaming them to freetype.lib and freetype.dll. You may want to copy the DLL to your C:\Windows\System or C:\Windows\System32 as well.

Copy the entire include directory from the FreeType sources to C:\ProgramFiles\Freetype\include.

Finally, add the directories C:\ProgramFiles\FreeType\include and C:\ProgramFiles\FreeType\include\freetype2 to your include path and add C:\ProgramFiles\FreeType\lib to your library path in Tools / Options / Project and Solutions / VC++ Directories. You can now use FreeType from Visual Studio.

Creating an Agar application in Visual Studio

You can now create your application. In the "Application Wizard", set "Application type" to "Console application", check the Empty project box and click Finish.

In the Solution Explorer, go to Properties from the popup menu of your project. Click on Configuration Properties / Linker / System and set the "SubSystem" parameter to "Windows (/SUBSYSTEM:WINDOWS)". Click on Configuration Properties / Linker / Input, and add the following to the Additional Dependencies field:

  • ag_gui.lib
  • ag_core.lib
  • winmm.lib
  • opengl32.lib (if OpenGL is enabled)
  • SDL.lib (if SDL is enabled)
  • SDLmain.lib (if SDL is enabled)
  • freetype.lib (if FreeType is enabled)
  • pthreadVC2.lib (if multithreading is enabled)

Add a new C++ file to Source Files in the Solution Explorer, such as main.cpp. Try the standard "Hello world":

  #include <agar/core.h>
  #include <agar/gui.h>
  
  int
  main(int argc, char *argv)
  {
          AG_Window *win;
          
          if (AG_InitCore(NULL, 0) == -1 ||
              AG_InitGraphics(0) == -1) {
		return (1);
	  }
          win = AG_WindowNew(0);
          AG_LabelNew(win, 0, "Hello, world!");
          AG_WindowShow(win);
          AG_EventLoop();
          return (0);
  }

Note: If you want your application to be portable to other operating systems and other development environments, consider the BSDBuild utility. Thanks to Premake, BSDBuild can even generate project files for you.

Compiling Agar itself with Visual Studio

If you are not using the precompiled SDK and would like to compile Agar yourself, look for the project files included in the .\ProjectFiles\ directory in the Agar source. Locate the .zip file matching your Visual C++ release, for example vs2005-windows.zip will work with all Visual C++ 2005 editions.

Unpack the archive into the very top Agar source directory.

Open Agar.sln with Visual Studio and compile. Once Agar is compiled, run INSTALL-SDK.EXE in the root of the Agar source directory to install the libraries on your system. By default, they are installed into C:\ProgramFiles\Agar.

Generating a custom Agar compilation profile

The set of project files included in Agar's .\ProjectFiles\ are automatically generated. These flavors were chosen for various popular combinations of IDE versions and platforms. The build may be configured using options (i.e., --disable-threads will disable multithreading support). If you wish to use a compilation profile not already available in .\ProjectFiles\, follow this procedure:

  • If you do not have Cygwin installed, install it (Download Cygwin). Make sure "Interpreters / perl" is enabled.
  • Download PREMAKE.EXE from the Premake website and copy it to Cygwin's /usr/local/bin directory. Choose the last version of the 3.0 series (Premake 4 is not backward compatible and is not currently supported).
  • Download BSDBuild from the BSDBuild website, install it with ./configure && make all install.
  • Find Makefile.proj in Agar's top-level source directory, open it up in a text editor. Add your entries to PROJFILES (see the commented-out example profiles at the bottom of Makefile.proj).
  • While still in Agar's top-level source directory, execute touch Makefile.config, then make proj from the Cygwin shell. If successful, the new project files will appear under .\ProjectFiles\.
  • Unpack the project files in the root of your Agar source directory.
Troubleshooting

If you've compiled with SDL support and are getting a linker error similar to:

  SDLmain.lib(SDL_win32_main.obj): error LNK2019: unresolved external symbol
  _SDL_main referenced in function _main

Then make sure SDL.h is included in your file with main() and that main() is declared exactly as follows:

  int main(int argc, char *argv)

If you are getting linker errors such as:

  error LNK2019: unresolved external symbol: "__imp__timeGetTime@0"
  in Funktion "_Init".

Then your "Linker / Input" settings are probably missing a library (in this example, winmm.lib is missing). The linker input settings are accessible from Solution Explorer, then "Properties" from the popup menu of your project. Click on Configuration Properties / Linker / Input, and add the missing libraries to the Additional Dependencies field. See the Creating an Agar application in Visual Studio section above for details.


If your program is not starting due to missing MSVCR100.DLL, make sure that the Visual C++ 2010 Redistributable Package is installed on your system. Any application compiled with Visual Studio depends on this library. Developers usually bundle a copy of the file with their application, or link statically against it (you can link statically by selecting the "Multi-threaded (/MT)" option under "C/C++ -> Code Generation").


If your program fails to start and Visual Studio is not reporting any useful information, make sure that all dependencies are compiled for the same architecture. As a last resort, try recompiling all libraries (pthreads, freetype, etc.) yourself.

Aero themes / OpenGL bugs under Vista / Windows 7

If you are using Agar's wgl driver (the default on Windows if opengl32.lib is available) and your application freezes a few seconds after focus is switched to a different application, this is due to an Aero-related bug affecting OpenGL applications. To disable Aero, right-click on the Windows Desktop, click on Personalize, and select a basic theme such as "Windows Classic".

Alternatively, you can work around this problem using a compatibility tweak: right-click on your application .exe file, go to Properties / Compatibility, and check the "Disable visual themes" option.


Hosted on multiple redundant OpenBSD servers at Csoft.net.
2014 Hypertriton, Inc. Opposed to software patents and DRM-encumbered devices!
Hosted by Csoft.net Eliminate DRM!