EnArBgDeElEsFaFiFrHiHuItJaKnKoMsNlPlPtRuSqThTrUkZh
- 2Creating a shared library
- 3Creating a static library
Visual Studio Solutions. If you use Visual Studio, you may want to pass -ide=vs to bin/gn gen to generate all.sln. That solution will exist within the GN directory for the specific configuration, and will only build/run that configuration. If you want a Visual Studio Solution that supports multiple GN configurations, there is a helper script. I have personally followed the procedure in Walkthrough: Creating and Using a Static Library (C) with a proper CUDA build customization and generation of relocatable code, but neither.obj nor.lib files have been generated. Is there a possibility to use the Visual Studio 2010 IDE to create a CUDA static library? Thank you very much in advance. Visual Studio for Mac; Visual Studio; Visual Studio for Mac walkthrough. This section walks through how to create and use a Portable Class Library using Visual Studio for Mac. Refer the to PCL Example section for a complete implementation. Adding a Portable Class Library to your solution is very similar to adding a regular.
For Android applications, Visual Studio for Mac includes its own designer, which works with Android.xml files to visually construct user interfaces. The iOS Designer is fully integrated with Visual Studio for Mac, allowing you to visually edit.xib and Storyboard files to create iOS, tvOS, and WatchOS UIs and transitions.
Introduction
This tutorial illustrates different approaches for using a custom library in your application on Windows. The first part explains how to create a shared library and how to link against it in your application. The second part is about creating and using a static library.
To organize a bigger project with libraries and executables, take a look at SUBDIRS - handling dependencies
Creating a shared library
When creating a shared library that you would like to link against, then you need to ensure that the symbols that are going to be used outside the library are properly exported when the library is created. Subsequently imported when you are linking against the library. This can be done using Q_DECL_EXPORT and Q_DECL_IMPORT as shown in the following example:
test.h
test.cpp
test.pro
On Windows, MinGW will output .a and .dll, MSVC will output .lib and .dll.
On Linux, gcc/clang will output .so, .so.1, .so.1.0 and .so.1.0.0 - .lib, .a and .so are import libraries. They help link your code to the library and is needed when you build your file(.a files not all the time).
See also the documentation on Creating Shared Libraries.
Linking your application against the shared library
In order to use the shared library in your application, then you can include the headers of your library in your code and use the methods. Compile with linking to the .lib file. At runtime this loads the dll which has the implementation.
To set this up, then in your application's .pro file you need to inform the application where to find the headers and the library. The INCLUDEPATH needs to point to the directory where the headers are installed, and the LIBS variable needs to point to the directory of the .lib file. In addition you need to ensure that the .dll is found by either putting it in the application's directory or in the global PATH.
For example:
loadTestLib.pro
main.cpp
alternatively you can right-click your project in Qt Creator and select 'Add Library...', choose 'External library' and browse for your library file:
- For libraries compiled with MSCV compiler in windows, you look for .lib or .dll
- On Windows, MinGW compiled linking libraries are in .a, but you will need to add it manually (as of Qt Creator 2.7). You could also try simply linking the .dll directly cause it would probably work. Don't try this with a MSVC compiled library .
- On Linux you look for the .so file
This will append the following code to your *.pro file:
$$PWD is used here to specify the full path leading to the directory containing your .pro file.
Note that for Unix/Linux systems the library file name is case sensitive, but for Windows you have to leave in all lower case.
Using QLibrary to load the shared library
QLibrary can be used for loading shared libraries at runtime. In this case you only need access to the .dll, access to the headers and .lib file(s) is not necessary.
The following example shows how to set up a library for usage with QLibrary. For the function names to be resolvable, they must be exported as C functions (i.e., without name mangling) from the library. This means that the functions must be wrapped in an extern 'C' block if the library is compiled with a C++ compiler.
Since we are doing this on Windows we also must explicitly export the function from the DLL using Q_DECL_EXPORT and Q_DECL_IMPORT.
qlibraryLibrary.pro
widget.h
widget.cpp
Loading the library using QLibrary
To load the library using QLibrary, you can simply pass in the .dll to the QLibrary constructor. Make sure the .dll is available in the application directory or in the global PATH. To use functions from the library in your application, you need to resolve them using QLibrary::resolve().
The example below loads the library created above and uses one of its functions to create and show a widget.
Creating a static library
When creating a static library you need to specify the staticlib option to CONFIG in the .pro file. In contrast to the shared library example, you don't need to set up anything special for exporting and importing symbols in your .h file, since the library will be built into the application, for example:
test.pro
Using the static library in your application
Similar to what we did for the shared library loading, you need to set up the INCLUDEPATH to point to the directory where the headers are installed and the LIBS variable to point to the .lib file, for example:
useStaticLib.pro
main.cpp
Installing a library
When you build your libraries, it could be useful to have one build for one framework and to centralize them : for example, you could having one library for Android, one for Windows and QT5.4 and one for Windows with Qt5.5 without having specific configurations.The easiest way is to put your files in the Qt folders by adding in your *.pro file :
You need to specify what files you want to copy with $$OUT_PWD and where you want to put them by using $$QT_INSTALL_HEADERS and $$QT_INSTALL_LIBS.
For more information, see Installing Files.
Which approach to choose
Which approach to choose depends on your needs. When creating a shared library, you need to deploy it with your application. On the plus side, applications and libraries linked against a shared library are small. Whether to use QLibrary to load the .dll or just standard linking, depends on whether you have access to the headers and the .lib files, if you don't have access to those, then QLibrary is an alternative.
Static linking results in a stand-alone executable. The advantage is that you will only have a few files to deploy. The disadvantage is that the executables are large. See the Deployment documentation for more details on shared and static builds.
Tip
Portable Class Libraries (PCLs) are considered deprecated in the latest versions of Visual Studio.While you can still open, edit, and compile PCLs, for new projects it is recommended to use.NET Standard librariesto access a larger API surface area.
A key component of building cross-platform applications is being able to share code across variousplatform-specific projects. However, this is complicated by the fact that different platforms often use adifferent sub-set of the .NET Base Class Library (BCL), and therefore are actually built to a different .NETCore Library Profile. This means that each platform can only use class libraries that are targeted to thesame profile so they would appear to require separate class library projects for each platform.
There are three major approaches to code sharing that address this problem: .NET Standard projects, Shared Asset Projects, and Portable Class Library (PCL) projects.
- .NET Standard projects are the preferred approach for sharing .NET code, read more about .NET Standard projects and Xamarin.
- Shared Asset Projects use a single set of files and offers a quick and simple way in which to share code within a solution and generally employs conditional compilation directives to specify code paths for various platforms that will use it (for more information see the Shared Projects article).
- PCL projects target specific profiles that support a known set of BCL classes/features. However, the down side to PCL is that they often require extra architectural effort to separate profile specific code into their own libraries.
This page explains how to create a PCL project that targets a specific profile,which can then be referenced by multiple platform-specific projects.
What is a Portable Class Library?
When you create an Application Project or a Library Project, the resulting DLL is restricted toworking on the specific platform it is created for. This prevents you from writing an assembly for a Windowsapp, and then re-using it on Xamarin.iOS and Xamarin.Android.
When you create a Portable Class Library, however, you can choose a combination of platforms that you wantyour code to run on. The compatibility choices you make when creating a Portable Class Library are translatedinto a “Profile” identifier, which describes which platforms the library supports.
The table below shows some of the features that vary by .NET platform. To write a PCL assembly that isguaranteed to run on specific devices/platforms you simply choose which support is required when you createthe project.
| Feature | .NET Framework | UWP apps | Silverlight | Windows Phone | Xamarin |
|---|---|---|---|---|---|
| Core | Y | Y | Y | Y | Y |
| LINQ | Y | Y | Y | Y | Y |
| IQueryable | Y | Y | Y | 7.5 + | Y |
| Serialization | Y | Y | Y | Y | Y |
| Data Annotations | 4.0.3 + | Y | Y | Y |
The Xamarin column reflects the fact that Xamarin.iOS and Xamarin.Android supports all the profiles shipped with Visual Studio, and the availability of features in any libraries you create will only be limited by the other platforms you choose to support.
This includes profiles that are combinations of:
- .NET 4 or .NET 4.5
- Silverlight 5
- Windows Phone 8
- UWP apps
You can read more about the different profiles' capabilities onMicrosoft’s websiteand see another community member's PCL profile summarywhich includes supported framework info and other notes.
Benefits
- Centralized code sharing – write and test code in a single project that can be consumed by other libraries or applications.
- Refactoring operations will affect all code loaded in the solution (the Portable Class Library and the platform-specific projects).
- The PCL project can be easily referenced by other projects in a solution, or the output assembly can be shared for others to reference in their solutions.
Disadvantages
- Because the same Portable Class Library is shared between multiple applications, platform-specific libraries cannot be referenced (eg. Community.CsharpSqlite.WP7).
- The Portable Class Library subset may not include classes that would otherwise be available in both MonoTouch and Mono for Android (such as DllImport or System.IO.File).
Note
Portable Class Libraries have been deprecated in the latest version of Visual Studio, and.NET Standard Libraries are recommended instead.
To some extent both disadvantages can be circumvented using the Provider pattern or Dependency Injection to code the actual implementation in the platform projects against an interface or base class that is defined in the Portable Class Library.
This diagram shows the architecture of a cross-platform application using a Portable Class Library to share code, but also using Dependency Injection to pass in platform-dependent features:
Visual Studio for Mac walkthrough
This section walks through how to create and use a Portable Class Library using Visual Studio for Mac. Refer the to PCL Example section for a complete implementation.
Creating a PCL
Adding a Portable Class Library to your solution is very similar to adding a regular Library project.
In the New Project dialog select the Multiplatform > Library > Portable Library option:
When a PCL is created in Visual Studio for Mac it is automatically configured with a Profile that works for Xamarin.iOS and Xamarin.Android. The PCL project will appear as shown in this screenshot:
The PCL is now ready for code to be added. It can also be referenced by other projects (Application projects, Library projects and even other PCL projects).
Editing PCL settings
To view and change the PCL settings for this project, right-click the project and choose Options > Build > General to see the screen shown here:
Click Change... to alter the target profile for this portable class library.
If the profile is changed after code has already been added to the PCL, it's possible that the library will no longer compile if the code references features that are not part of the newly-selected profile.
Working with a PCL
When code is written in a PCL library, the Visual Studio for Mac editor will recognize the limitations of the selected profile and adjust auto-complete options accordingly. For example, this screenshot shows the auto-complete options for System.IO using the default profile (Profile136) used in Visual Studio for Mac – notice the scrollbar which indicates about half of the available classes are displayed (in fact there are only 14 classes available).
Compare that with the System.IO auto-complete in a Xamarin.iOS or Xamarin.Android project – there are 40 classes available including commonly used classes like File and Directory which are not in any PCL profile.
This reflects the underlying trade-off of using PCL – the ability to share code seamlessly across many platforms means certain APIs are not available to you because they don’t have comparable implementations across all possible platforms.
Using PCL
Visual Studio C++ For Mac
Once a PCL project has been created, you can add a reference to it from any compatible Application or Library project in the same way you normally add references. In Visual Studio for Mac, right-click on the References node and choose Edit References... then switch to the Projects tab as shown:
The following screenshot shows the Solution pad for the TaskyPortable sample app, showing the PCL library at the bottom and a reference to that PCL library in the Xamarin.iOS project.
The output from a PCL (ie. the resulting assembly DLL) can also be added as a reference to most projects. This makes PCL an ideal way to ship cross-platform components and libraries.
Visual Studio walkthrough
This section walks through how to create and use a Portable Class Library using Visual Studio. Refer the toPCL Example section for a complete implementation.
Creating a PCL
Adding a PCL to your solution in Visual Studio is slightly different to adding a regular project:
In the Add New Project screen, select the Class Library (Legacy Portable) option. Note the description on the right advises that this project type has been deprecated.
Visual Studio will immediately prompt with the following dialog so that the profile can be configured.Tick the platforms you need to support and press OK.
The PCL project will appear as shown in the Solution Explorer – the text (Portable) appears beside the project name to indicate it is a PCL:
The PCL is now ready for code to be added. It can also be referenced by other projects (applicationprojects, library projects, and even other PCL projects).
Visual Studio For Mac Review
Editing PCL settings
The PCL settings can be viewed and changed by right-clicking on the project and choosing Properties > Library , as shown in this screenshot:
If the profile is changed after code has already been added to the PCL, it’s possible that the library will no longer compile if the code references features that are not part of the newly-selected profile.
Tip
There is also a message advising that .NETStandard is the recommended method for sharing code. This is an indication that while PCLs are still supported, it is recommended to upgrade to .NET Standard.
Working with a PCL
When code is written in a PCL library, Visual Studio will recognize the limitations of the selected profile and adjust Intellisense options accordingly. For example, this screenshot shows the auto-complete options for System.IO using the default profile (Profile136) – notice the scrollbar which indicates about half of the available classes are displayed (in fact there are only 14 classes available).
Compare that with the System.IO auto-complete in a regular project – there are 40 classes available includingcommonly used classes like File and Directory which are not in any PCL profile.
This reflects the underlying trade-off of using PCL – the ability to share code seamlessly across many platforms means certain APIs are not available to you because they don’t have comparable implementations across all possible platforms.
Tip
.NET Standard 2.0 represents a much larger API surface area than PCLs, including the System.IO namespace. For newprojects, .NET Standard is recommended over PCL.
Using PCL
Once a PCL project has been created, you can add a reference to it from any compatible Application or Library project in the same way you normally add references. In Visual Studio, right-click on the References node and choose Add Reference... then switch to the Solution > Projects tab as shown:
The following screenshot shows the Solution pane for the TaskyPortable sample app, showing the PCL library at the bottom and a reference to that PCL library in the Xamarin.iOS project.
The output from a PCL (ie. the resulting assembly DLL) can also be added as a reference to most projects.This makes PCL an ideal way to ship cross-platform components and libraries.
PCL example
The TaskyPortablesample application demonstrates how a Portable Class Library can be used with Xamarin.Here are some screenshots of the resulting apps running on iOS and Android:
It shares a number of data and logic classes that are purely portable code, and it also demonstrates how toincorporate platform-specific requirements using Dependency Injection for the SQLite database implementation.
The solution structure is shown below (in Visual Studio for Mac and Visual Studio respectively):
Because the SQLite-NET code has platform-specific pieces (to work with the SQLite implementations on each different operating system) for demonstration purposes it has been refactored into an abstract class that can be compiled into a Portable Class Library, and the actual code implemented as subclasses in the iOS and Android projects.
TaskyPortableLibrary
The Portable Class Library is limited in the .NET features that it can support. Because it is compiled to run on multiple platforms, it cannot make use of [DllImport] functionality that is used in SQLite-NET. Instead SQLite-NET is implemented as an abstract class, and then referenced through the rest of the shared code. An extract of the abstract API is shown below:
The remainder of the shared code uses the abstract class to “store” and “retrieve” objects from the database. In any application that uses this abstract class we must pass in a complete implementation that provides the actual database functionality.
TaskyAndroid and TaskyiOS
The iOS and Android application projects contain the user-interface and other platform-specific code used to wire-up the shared code in the PCL.
These projects also contain an implementation of the abstract database API that works on that platform. OniOS and Android the Sqlite database engine is built-in to the operating system, so the implementation can use[DllImport] as shown to provide the concrete implementation of database connectivity. An excerpt of the platform-specific implementation code is shown here:
The full implementation can be seen in the sample code.
Summary
This article has briefly discussed the benefits and pitfalls of Portable Class Libraries, demonstrated how to create and consume PCLs from inside Visual Studio for Mac and Visual Studio; and finally introduced a complete sample application – TaskyPortable – that shows a PCL in action.