For the latest documentation and news visit http://xlw.sourceforge.net/ Please post feedback to xlw-users@sourceforge.net PLEASE REFER TO THE LICENSE FILE. Getting Started =============== If you have installed this from the self-extracting installer the should be in the menu a link to the examples. This is probably the best place to start. There are also menu items for Template Extractors which you can use to create a new fresh xll project, either under xlw(vanilla) or xlwDotNet. At this stage the most important factor to a speedy release version is feedback from the users Please email xlw-users@lists.sourceforge.net. If you will be using MinGW ( inc Code::Blocks & Dev-CPP ) then please also read the MinGW section of the documentation below. =================================================================================================== --------------------------------------------------------------------------------------------------- =================================================================================================== PRE-REQUISITE ============= C++ XLLs -------- Developing C++ with XLW requires one of the following environments : 1. MicroSoft Visual Studio 2008 with both C++ (VS9_PRO) 2. MicroSoft Visual Studio 2005 with both C++ (VS8_PRO) 3. Visual Studio 2008 Express Editions C++ (VS9_EXPRESS) 4. Visual Studio 2005 Express Editions C++ (VS8_EXPRESS) 5. Visual Studio 2003 (VS7.1) 6. Code::Blocks 8.02 (installer WITHOUT MinGW) + MinGW/GCC4.4.0 ( See section on MinGW below) (C::B/MinGW) 7. Dev-C++ v5.0 beta 9.2 (Installer WITHOUT MinGW) + MinGW/GCC4.4.0 ( See section on MinGW below) (Dev-C++) 8. MinGW/GCC/Make enviroment (GCC/MAKE) C# XLLs -------- Developing C# XLLs with XLW requires one of the following Microsoft Visual Studio environments : 1. MicroSoft Visual Studio 2008 with both C++ and C# installed. (VS9_PRO) 2. MicroSoft Visual Studio 2005 with both C++ and C# installed. (VS8_PRO) 3. Visual Studio 2008 Express Editions C++ & Visual Studio 2008 Express Editions C# (VS9_EXPRESS) 4. Visual Studio 2005 Express Editions C++ & Visual Studio 2005 Express Editions C# (VS8_EXPRESS) There is no support for Visual Studio 2002 & 2003 and none is planned. 1. Visual Studio 2005 Express Edition (VS8_EXPRESS) ''''''''''''''''''''''''''''''''''''''''''''''''' Visual C++ 2005 Express is not shipped with the Microsoft Platform SDK. This is a pre-requisite for developing with xlw. It can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en If you are using the Express edition of Visual C++ 2005, you need to install this first. The standard package will install to C:\Program Files\Microsoft SDKs\Windows. You need to set the environment Variable PSDK to the path of the SDK. For me the variable PSDK is set to C:\Program Files\Microsoft SDKs\Windows\v6.1 on one machine and set to C:\Program Files\Microsoft SDKs\Windows\v6.0A on a different machine. If you already had Visual Studio open when you set the environment variable PSDK you have to close it and re-open it for the new environment variable to be recognised. These extra few steps are only neccassary for the EXPRESS edition of VC 2005. They are NOT neccassary for Visual C++ 2005 Professional. 2. Building an XLL with xlw (C++) ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 2.1 Obtaining the Template Project --------------------------------- Obtain a template project from the xlw template extractor in the XLW submenu of Start 2.2 Naming your Library ---------------------- 3. Building an XLL with xlwDotNet (C#, VisualBasic or Hybrid C#/C++) ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 3.1 Obtaining the Template Project --------------------------------- Obtain a template project from the xlwDotNet template extractor in the XLW submenu of Start 3.2 Naming your Library ---------------------- The name of you xll addin and associated libraries, will be taken from the names of the Visual Studio Solutions NOT the constituent Visual Studio Projects. We will change the name in 3 places. i. Change the name of your Template directory from XLL_Project to MyLib, replacing MyLib with the name of your Library. ii. In this directory You will find a Visual Studio Solution file called Template.sln, change the name to MyLib.sln replacing MyLib with the name of your Library. iii. Also in this directory you will find a sub-directory Addin, in this sub directory you will see a C++ Solution file Template.sln ( unless you are building a Hybrid project). Change the name of this to MyLib.Sln replacing MyLib with the name of your Library. iv. You can now open with Visual Studio the original renamed Solution file (i.e the one u renamed in (ii) ) Build this Solution to see if everything is ok. If not check your variable XLW is set correctly. You may have to restart you Visual Studio. 3.3 Adding your own functions in C# ---------------------------------- The parameter and return types of you functions can be : MyMatrix MyArray double[] double[,] string double int CellMatrix ArgumentList When you write your functions : i. Decorate each function with the attribute [ExcelExport("function description goes here")] ii. Decorate each parameter with the attribute [Parameter("parameter description goes here ")] iii. Ensure the function is public and static. Ensure that the method is in a Public class. A function would then look like this : [ExcelExport("returns the diff of two cell ranges")] public static CellMatrix DiffRange( [Parameter("The first Cell Range")] CellMatrix A, [Parameter("The second Cell Range")] CellMatrix B ) { .... } Your functions must be Public & static and in a Public class. 3.4 Adding your own functions in VisualBasic --------------------------------------------- _ Public Shared DiffRange( _ CellMatrix A, _ CellMatrix B _ ) as xlwTypes.CellMatrix { .... } 4. Tweaking Visual Studio Express ''''''''''''''''''''''''''''''' The default install of Visual Studio ( C++, C# or VisualBasic) does not show the the build configuration at the top as is the case for the Professional Edition. This can be changed by going to Tools->Options then checking the box 'Show All Settings'. Then from the menu in the list on the left select 'Projects and Solutions -> General' then check boxes "Show advanced build configurations' and 'Show Output window when build starts' 5. If Your .NET Addin Just crashes Excel. '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' < THIS STEP SHOULD BE TAKEN CARE OF BY THE INSTALLER > Some versions of Excel do not load the correct .NET Runtime. .NET 2.0, .NET 3.0 & .NET 3.5 are all shipped with CLR v2 (v2 of the runtime) An xll built by xlwDotNet requires this runtime. To force Excel to to load this runtime at startup there is a work around. Create a file called Excel.exe.config with contents : and put it in the same directory as the excel executable. Some other reading on this issue http://stackoverflow.com/questions/436958/-net-app-config-question http://krgreenlee.blogspot.com/2006/01/software-running-excel-with-net-11.html http://msdn.microsoft.com/en-us/library/w4atty68.aspx 6. Debugging .NET xlls ''''''''''''''''''''''' In the directory Addin of your XLL project along with your project file DotNet.csproj you may find the file DotNet.csproj.user, if not create it with a text editor. In that file put the following text : Program C:\Program Files\Microsoft Office\Office10\EXCEL.EXE But replace the ..... with the path to your own Excel executable. If you have your C# or VB.NET project open you will need to close it and reopen. Now you can set breakpoints in your .NET code and debugging will start Excel. When Excel is started just open your xll addin .. and you should be debugging. see this blog of you need more details http://through-the-interface.typepad.com/through_the_interface/2006/07/debugging_using.html ( For hybrid projects debugging should be more straight forward ) 7.Visual Studio 2005 Professional ''''''''''''''''''''''''''''''''' When building xll projects you may get a warning about non-existent environment variable $PSDK. This warning can be ignored. 8. Some Useful Video Clips '''''''''''''''''''''''''' Creating a C++ XLL with Visual Studio 2008 http://www.youtube.com/watch?v=_mpw5_JW7T4 Creating a C# XLL with Visual Studio 2008 http://www.youtube.com/watch?v=1yLodcb32sI Creating a C++ XLL with Code::Blocks & MinGW http://www.youtube.com/watch?v=UmkSLesszqQ Creating a hybrid C++/C# XLL with Visual Studio (Professional) 2008 http://www.youtube.com/watch?v=xJmKM4dwEEU Debugging a C# XLL with Visual C# Express 2008 http://www.youtube.com/watch?v=Obtg8iVniQQ =================================================================================================== --------------------------------------------------------------------------------------------------- =================================================================================================== MinGW Section ============= 1. Getting the latest MinGW ---------------------------- Recently MinGW has updated its GCC compiler suite to GCC4.4. This version of XLW ( 4.0.0 beta 2 ) has been updated to reflect this change in MinGW. The dependency in XLW on the earlier version of GCC (3.4.5) has been replaced by the dependency on the newer GCC shipped with the latest MinGW ( imminent). Unfortunatley the MinGW automatic installer has not been updated to install the new compiler suite and if used for installation will still install the older GCC, with which XLW will no longer work ( unless compiled from source). In this case the normal way around would be to install MinGW manualy without the automatical installer, however this can be somewhat tedious. In order to keep the installation, usage and overall experience of XLW simple and painless we have built a MinGW installer that will download and install all the necessary MinGW components required for C/C++ compilation and to resolve XLW's dependency. You will find the MinGW installer, 'xlw-MinGW-Installer.exe' on the xlw sourceforge webpage under the download section for 'MingW Installer'. This will install all GCC4.4 & MSYS ( from the offical MinGW download site )and put the appropriate Bin directories on the Path. It is however not necessary to use THIS installer to get the latest version of MinGW, another installer is provided by TDM which can be found here : http://www.tdragon.net/recentgcc/ Also the necessary components can be downloaded manualy. The requirements are MinGW ----- gcc-core-4.4.0-mingw32-bin.tar.gz gcc-core-4.4.0-mingw32-dll.tar.gz gcc-c++-4.4.0-mingw32-bin.tar.gz gcc-c++-4.4.0-mingw32-dll.tar.gz gcc-4.4.0-mingw32-notes.txt mingw32-make-3.81-20080326-3.tar.gz mingwrt-3.16-mingw32-dll.tar.gz mingwrt-3.16-mingw32-dev.tar.gz binutils-2.19.1-mingw32-bin.tar.gz mpfr-2.4.1-mingw32-dll.tar.gz pthreads-w32-2.8.0-mingw32-dll.tar.gz gmp-4.2.4-mingw32-dll.tar.gz w32api-3.13-mingw32-dev.tar.gz libiconv-1.13.1-1-mingw32-bin.tar.lzma MSYS ---- msysCORE-1.0.11-bin.tar.gz GDB ---- gdb-6.8-mingw-3.tar.bz2 2. Code::Blocks ---------------- On the Code::Blocks download site there are 2 installers available. One without MinGW and one with. Previously it was advised to install the one with the MinGW. However now you should install the one WITHOUT MinGW, since the MinGW packaged in the Code::Blocks installer is the older version. To setup Code::Blocks firstly install the latest MinGW ( GCC4.4 ) as described above. Then in Code::Blocks goto 'Settings->Compiler & Debugger -> Toolchain executables' and set the Compilers installation directory to the bin directory of your MinGW installation (if you used the xlw MinGW installer and installed to the default directory, this should be C:\GNU\MinGW) 3. Dev-CPP ---------------- You should install the latest MinGW as decsribed above and then install the Dev-CPP package without the inclusive MinGW software from the download page.