1# antimicro 2 3## We've Moved! 4 5As of May 24, 2016, antimicro has moved from 6[https://github.com/Ryochan7/antimicro](https://github.com/Ryochan7/antimicro) to 7[https://github.com/AntiMicro/antimicro](https://github.com/AntiMicro/antimicro). 8Additionally, project management has passed from Travis (Ryochan7) to the AntiMicro 9organization due to Travis having other interests and priorities. 10 11So, thank you for your patience as we settle in. And a special thank you to the 12following GitHub users who have helped us make the transition: 13* 7185 14* DarkStarSword 15* est31 16* ProfessorKaos64 17* qwerty12 18* WAZAAAAA0 19* zzpxyx 20 21## Description 22 23antimicro is a graphical program used to map keyboard keys and mouse controls 24to a gamepad. This program is useful for playing PC games using a gamepad that 25do not have any form of built-in gamepad support. However, you can use this 26program to control any desktop application with a gamepad; on Linux, this 27means that your system has to be running an X environment in order to run 28this program. 29 30This program is currently supported under various Linux 31distributions, Windows (Vista and later), and FreeBSD. At the time of writing 32this, antimicro works in Windows XP but, since Windows XP is no longer 33supported, running the program in Windows XP will not be officially supported. 34However, efforts will be made to not intentionally break compatibility 35with Windows XP. 36 37Also, FreeBSD support will be minimal for now. I don't use BSD on 38a daily basis so the main support for FreeBSD is being offered by Anton. He 39has graciously made a port of antimicro for FreeBSD that you can find 40at the following URL: [http://www.freshports.org/x11/antimicro/](http://www.freshports.org/x11/antimicro/). 41 42## License 43 44This program is licensed under the GPL v.3. Please read the gpl.txt text document 45included with the source code if you would like to read the terms of the license. 46The license can also be found online at 47[http://www.gnu.org/licenses/gpl.txt](http://www.gnu.org/licenses/gpl.txt). 48 49## Download 50Source code archives and Windows binaries are available from the antimicro 51Releases section on GitHub: 52 53[https://github.com/AntiMicro/antimicro/releases](https://github.com/AntiMicro/antimicro/releases) 54 55AntiMicro is currently in the official Fedora repository and can be installed with 56 57`$ sudo dnf install antimicro` 58 59For Debian and Debian-based distributions, such as Mint, Ubuntu, and Steam OS, please check the LibreGeek 60Repositories generously hosted by ProfessorKaos64: 61 62[http://packages.libregeek.org/](http://packages.libregeek.org/) 63 64AntiMicro is currently available for Slackware via SlackBuilds, thanks to NK and Klaatu: 65 66[https://slackbuilds.org/result/?search=antimicro&sv=](https://slackbuilds.org/result/?search=antimicro&sv=) 67 68Ubuntu users may also check the antimicro page on Launchpad: 69 70[https://launchpad.net/~ryochan7/+archive/ubuntu/antimicro](https://launchpad.net/~ryochan7/+archive/ubuntu/antimicro) 71 72## Command line 73 74 Usage: antimicro [options] [profile] 75 76 Options: 77 -h, --help Print help text. 78 -v, --version Print version information. 79 --tray Launch program in system tray only. 80 --no-tray Launch program with the tray menu disabled. 81 --hidden Launch program without the main window 82 displayed. 83 --profile <location> Launch program with the configuration file 84 selected as the default for selected 85 controllers. Defaults to all controllers. 86 --profile-controller <value> Apply configuration file to a specific 87 controller. Value can be a 88 controller index, name, or GUID. 89 --unload [<value>] Unload currently enabled profile(s). 90 Value can be a controller index, name, or GUID. 91 --startSet <number> [<value>] Start joysticks on a specific set. 92 Value can be a controller index, name, or GUID. 93 -d, --daemon Launch program as a daemon. 94 --log-level (debug|info) Enable logging. 95 --eventgen (xtest|uinput) Choose between using XTest support and uinput 96 support for event generation. Default: xtest. 97 -l, --list Print information about joysticks detected by 98 SDL. 99 --map <value> Open game controller mapping window of selected 100 controller. Value can be a controller index or 101 GUID. 102 103## Pre-made Profiles 104 105There is a repository for pre-made antimicro profiles. Using a pre-made 106profile, you can have a controller layout that is suitable for playing a 107game without having to map everything yourself. It makes using antimicro 108really convenient. In order to use those pre-made profiles, you have to be 109running at least antimicro version 2.0 and antimicro must have been compiled 110with SDL 2 support. 111 112[https://github.com/AntiMicro/antimicro-profiles](https://github.com/AntiMicro/antimicro-profiles) 113 114## Wiki 115 116An effort is now being done to utilize the Wiki section on GitHub more. 117Please check out the Wiki at [https://github.com/AntiMicro/antimicro/wiki](https://github.com/AntiMicro/antimicro/wiki) 118to read various help pages that have been created. The Wiki is currently 119open to all GitHub users so feel free to add a new page or modify an 120existing page. 121 122## Build Dependencies 123 124This program is written in C++ using the [Qt](https://www.qt.io/) 125framework. A C++ compiler and a proper C++ build environment will need to be 126installed on your system prior to building this program. Under Debian and 127Debian-based distributions like Ubuntu, the 128easiest way to get a base build environment set up is to install the 129meta-package **build-essential**. The following packages are required to be 130installed on your system in order to build this program: 131 132* g++ 133* cmake 134* libqt4-dev (Qt 4 support) or qttools5-dev and qttools5-dev-tools (Qt 5 135support) 136* libsdl1.2-dev (SDL 1.2) or libsdl2-dev (SDL 2) 137* libxi-dev (optional. Needed to compile with X11 and uinput support) 138* libxtst-dev (optional. Needed to compile with XTest support) 139* libX11-dev (optional when compiled with Qt 5 support) 140 141## Building under Linux 142 143In order to build this program, open a terminal and cd into the antimicro 144directory. Enter the following commands in order to build the program: 145 146 cd antimicro 147 mkdir build && cd build 148 cmake .. 149 make 150 sudo make install 151 152The installation path of antimicro can be customized by specifying the 153CMAKE_INSTALL_PREFIX variable while running cmake. 154 155 cmake -DCMAKE_INSTALL_PREFIX=/usr .. 156 157This will install the antimicro executable to /usr/bin/antimicro. 158By default, the executable will be installed to /usr/local/bin/antimicro. 159 160The cmake step will use pkg-config to attempt to find any SDL 161libraries that you have installed. The project is set up to 162look for a copy of SDL 2 followed by SDL 1.2. This behavior should work 163fine for most people. You can override this behavior by using the -DUSE_SDL_2 164option when you run cmake. Using -DUSE_SDL_2=ON when you run cmake will mean 165that you want antimicro compiled with SDL 2 support. Using -DUSE_SDL_2=OFF when 166you run cmake will mean that you want antimicro compiled with SDL 1.2 support. 167 168Here is an example of how to specify that you want antimicro to be compiled 169with SDL 2 support when you run qmake. 170 171 cmake -DUSE_SDL_2=ON .. 172 173## Building under Windows 174 175**Instructions provided by aybe @ https://github.com/aybe. 176Modified by Travis Nickles.** 177 178* Download and install CMake: http://www.cmake.org/cmake/resources/software.html 179 180* You will need Qt with MinGW support: https://www.qt.io/download-open-source/. The 181current version of Qt that is being used to create builds is 5.6.0. 182 183* download SDL development package : http://www.libsdl.org/release/SDL2-devel-2.0.3-mingw.tar.gz 184 185* open the archive and drop the 'SDL2-2.0.3' folder in the 'antimicro' folder 186 187* open the project (CMakeLists.txt) in Qt Creator The CMake Wizard will appear 188the first time you open the project in Qt Creator. 189 190* Choose a Build Location. The recommendation is to create a "build" folder 191under the root antimicro folder and choose that for the build location. 192 193* In the Run CMake section, in the Arguments field, please input 194```-DCMAKE_PREFIX_PATH=<Path to MinGW Qt install>``` 195-DCMAKE_BUILD_TYPE=Release. Replace "```<Path to MinGW Qt install>```" 196with the actual path to your Qt installation. The default path for version 197Qt 5.6.0 is C:\Qt\Qt5.6.0\5.6\mingw49_32\. 198 199* Choose "MinGW Generator" for the Generator option in the Run CMake section 200 201* Click the Run CMake button and then click Finish 202 203* In the main IDE window, open the Build menu and select "Build All" (Ctrl+Shift+B) 204 205* The application will need SDL2.DLL. A build step has been added to 206CMakeLists.txt in order to automate the process. Click the "Projects" icon 207in the sidebar to bring up the "Build Settings" section. Within 208"Build Steps", click the "Details" button on the Make entry. In the expanded 209menu, uncheck the "all" checkbox and then check the "copy_sdl_dll" checkbox 210and run "Build All". 211 212* At this point, antimicro has been built for Windows and is runnable 213from Qt Creator. A couple more steps are required in order to make a 214distributable package. 215 216* Under "Build Settings", expand the Make menu and check the "install" and 217"install_dlls" checkboxes. 218 219* Under the "Build" menu in the main window, select "Run CMake" and 220add ```-DCMAKE_INSTALL_PREFIX=<DIR>``` option and replace ```<DIR>``` with the directory 221that you want to install the application. The default for me is 222C:\Program Files (x86)\AntiMicro\ although I use a different directory 223when bundling the Window version for other users. 224 225* Run "Build All" to have the application and required DLLs installed 226into the final location that will be ready for distribution. 227 228### 64 bit build 229 230* Some additional steps are required in order to compile a 64 bit version of 231antimicro. The first step is to download a packaged version of Qt and MinGW 232compiled for 64 bit from the Qt-x64 project @ 233http://sourceforge.net/projects/qtx64/. 234 235* You will have to manually create a new Kit in Qt Creator. In the main Qt 236Creator window, click the "Projects" button in the sidebar to bring up the 237"Build Settings" page for the project. Click on the "Manage Kits" button 238near the top of the page. Manually add the 64 bit compiled Qt version under 239"Qt Versions", add the 64 bit MinGW under "Compilers", and add the 64 bit 240gdb.exe under "Debuggers". 241 242* After creating a new kit in Qt Creator, bring up the "Build Settings" page 243for the project. Hover over the currently selected kit name and click the 244arrow that appears, hover over "Change Kit" and select the proper 64 bit kit 245that you created earlier. 246 247* Perform a clean on the project or delete the build directory that CMake is 248using. After that, choose the "Run CMake" option under the "Build" menu entry. 249The arguments that you pass to CMake will have to be changed. You will have 250to edit ```-DCMAKE_PREFIX_PATH=<Path to 64 bit MinGW Qt install>``` variable 251and have it point to the 64 bit compiled version Qt. Also, make sure to add 252```-DTARGET_ARCH=x86_64``` so that CMake will use the proper SDL libraries while 253building the program and copy the proper Qt and SDL DLLs if you perform an 254**install_dlls**. 255 256## Building the Windows Installer Package (MSI) 257 258(these instructions have been tested with WiX 3.8) 259 260* you need to have WiX installed, grab it at http://wixtoolset.org/ 261 262* the building process relies on the WIX environment, it is recommended that you download the installer instead of the binaries as it it will set it up for you 263 264* if Qt Creator is running while you install or upgrade to a newer version then make sure to restart it as it will either not find that environment variable or fetch the old (incorrect) value from the previous version 265 266* to build the MSI package, click on the "Projects" icon in the sidebar, 267click the "Details" button on the make entry, uncheck all other options 268and check the "buildmsi" box. 269 270* currently it relies on INSTALL to copy files at the location they are harvested, this might change in the future 271 272Notes about the WXS file and the building process : 273 274* the WXS file has been generated with WixEdit and manually modified to contain relative paths, it will only work from the 'windows' sub-folder (or any other) 275 276* WixCop can be run against the WXS file and it should not point out any errors as the WXS has been corrected previously with the -F switch 277 278* CNDL1113 warning : shortucts are advertised, left as-is as a nice feature about them is that if the program gets corrupted it will be repaired by Windows Installer, by design the shortcuts will not point to antimicro.exe as a regular LNK file 279 280* LGHT1073 warning : SDL2.DLL does not specify its language in the language column, not a big deal; it could be recompiled but it's pretty much a time waste as it would only prevent this warning 281 282* all of these warnings have been made silent through the use of command-line switches. 283 284* built MSI package will be placed in /windows 285 286## Testing under Linux 287 288If you are having problems with antimicro detecting a controller or 289detecting all axes and buttons, you should test the controller outside of 290antimicro to check if the problem is with antimicro or not. The two endorsed 291programs for testing gamepads outside of antimicro are **sdl-jstest** 292(**sdl2-jstest**) and **evtest**. SDL 2 utilizes evdev on Linux so performing 293testing with older programs that use joydev won't be as helpful since some 294devices behave a bit differently between the two systems. 295 296[https://github.com/Grumbel/sdl-jstest/](https://github.com/Grumbel/sdl-jstest/) 297 298## Support 299 300In order to obtain support, you can post an issue on the antimicro GitHub page 301or you can email me at jeff@jsbackus.com. Please include **antimicro** 302somewhere in the subject line of the email message or it might be skipped. 303 304[https://github.com/AntiMicro/antimicro](https://github.com/AntiMicro/antimicro) 305 306## Ideas For Future Features 307 308This section is where some of the ideas for future features 309for this program will be written. 310 311* Allow buttons to be bound to actions. 312* Use uinput by default and fallback to XTest if necessary. (MOSTLY DONE) 313* Move simulated event generation to a new thread. 314* ~~Allow logging as long as it doesn't cause button lag.~~ 315* Allow notes to be added to a profile in various places. 316 317Along with this, I will put the simple mind map that I am using to 318write ideas for future development into the repository for this 319program. The mind map will include extra notes that are not available in 320this README. Opening the mind map will require the use of the program 321FreeMind which can be downloaded from 322[http://freemind.sourceforge.net/wiki/index.php/Main_Page](http://freemind.sourceforge.net/wiki/index.php/Main_Page). 323 324## Translating 325 326New translations as well as updates to current translations are always welcome. 327Please refer to 328[https://github.com/AntiMicro/antimicro/wiki/Translating-AntiMicro](https://github.com/AntiMicro/antimicro/wiki/Translating-AntiMicro) 329 330## Shoutout 331 332A big inspiration for this program was the program QJoyPad 333([http://qjoypad.sourceforge.net/](http://qjoypad.sourceforge.net/)). 334I was a user of the program for years and it is unfortunate that the 335program is no longer being maintained. The source code for QJoyPad was an 336invaluable resource when I made the first version of this program and the UI 337for this program mostly resembles QJoyPad. 338 339## Credits 340 341### Original Developer 342Travis Nickles <nickles.travis@gmail.com> 343 344### Contributors 345 346Zerro Alvein 347aybe 348Jeff Backus <jeff@jsbackus.com> 349Arthur Moore 350Anton Tornqvist <antont@inbox.lv> 351 352### Translators 353 354VaGNaroK <vagnarokalkimist@gmail.com> - Brazilian Portuguese 355zzpxyx - Chinese 356Belleguic Terence <hizo@free.fr> - French 357Leonard Koenig <leonard.r.koenig@googlemail.com> - German 358phob - German 359tou omiya - Japanese 360Dmitriy Koshel <form.eater@gmail.com> - Russian 361Jay Alexander Fleming <tito.nehru.naser@gmail.com> - Serbian 362burunduk - Ukrainian 363Flavio HR <flavio.hrx@gmail.com> - Spanish 364WAZAAAAA - wazaaaaa00<@>gmail<.>com - Italian 365