README.MSVC.md
1Building libpsl with Visual Studio
2==================================
3
4Building libpsl for Windows using Visual Studio 2008 or later is
5supported with NMake (from release tarballs) or Meson (from GIT
6checkouts). The following sections will cover building libpsl with
7these methods.
8
9Currently, for builtin/runtime public suffix list (PSL) IDNA handling,
10only ICU is supported for Visual Studio builds.
11
12Using NMake (from a release tarball)
13===========
14You will need a Python 2.7.x or later installation in order to
15complete the build successfully.
16
17You will need the ICU (International Components for Unicode)
18libraries, headers and DLLs, to build libpsl, unless both
19DISABLE_BUILTIN=1 and DISABLE_RUNTIME=1 are passed into the NMake
20command line as listed below.
21
22You can also buid libpsl with libiconv and gettext support, please
23see the options below for enabling such support.
24
25In a Visual Studio command prompt which matches your desired
26configuration (x86/Win32, x64 etc.),
27go to $(srcroot)\msvc, and issue the following command:
28
29nmake /f Makefile.vc CFG=[debug|release]
30
31A 'test' target is provided to build the test programs, while a
32'clean' target is provided to remove all the compiled and generated
33files for the build. An 'install' target is provided to copy the
34build PSL DLL, .lib and executables, as well as the related PDB files
35and libpsl header, into appropriate locations under PREFIX (please see
36below).
37
38This will build the libpsl DLL/LIB and the psl.exe utility in the
39vsX\$(CFG)\$(ARCH) subdirectory, where X is the release version
40of Visual Studio, such as 9 for 2008 and 16 for 2019, and ARCH is
41Win32 for 32-bit builds and x64 for 64-bit (x86_64) builds.
42
43A number of options can be passed into the NMake command, as follows.
44Enable by setting each option to 1, unless otherwise indicated:
45
46* PSL_FILE: Location of the PSL data file, which is retrieved from
47 https://publicsuffix.org/list/public_suffix_list.dat,
48 or some other custom location (not supported). Default
49 is in $(srcroot)\list\public_suffix_list.dat. This is
50 needed to generate the suffixes_dafsa.h header required
51 for the build, as well as the binary and ascii dafsa
52 files used for the test programs.
53
54* TEST_PSL_FILE: Location of the test PSL file. Default is in
55 $(srcroot)\list\tests\tests.txt. This is
56 required for building and running the test
57 programs.
58
59* STATIC: Set if building static versions of libpsl is desired.
60
61* USE_LIBTOOL_DLLNAME: Set to use libtool-style DLL naming.
62
63* DISABLE_RUNTIME: Do not use ICU to generate runtime PSL data.
64
65* DISABLE_BUILTIN: Do not use ICU to generate builtin PSL data.
66
67* USE_ICONV: Enable libiconv support, requires libiconv.
68
69* USE_GETTEXT: Enable gettext support for displaying i18n messages.
70 Implies USE_ICONV, and requires gettext-runtime.
71
72* PYTHON: Full path to a Python 2.7.x (or later) interpreter, if not
73 already in your PATH.
74 Required to generate DAFSA headers and data files that is
75 needed for the build, as well as generating pkg-config
76 files for NMake builds.
77
78* PREFIX: Base installation path of the build. Note that any dependent
79 libraries are searched first from the include\ and lib\
80 sub-directories in PREFIX before searching in the paths
81 specified by %INCLUDE% and %LIB%. Default is
82 $(srcroot)\..\vsX\$(PLATFORM), where X is the release version
83 of Visual Studio, such as 9 for 2008 and 16 for 2019,
84 $(PLATFORM) is the target platform (Win32/x64) of the build.
85
86Building libpsl with Meson
87==========================
88Building using Meson is now supported for Visual Studio builds from a
89GIT checkout.
90
91Besides the requirements listed in the NMake builds, you will also need
92
93* Python 3.5.x or later
94* Meson build system, use PIP to install from Python 3.5.x64
95* Ninja build tool (if not involking Meson with --backend=
96 vs[2010|2015|2017|2019])
97* A compatible PSL data file and a test PSL data file. You may
98 consider using the ones shipped with the latest libpsl release
99 tarball and place the PSL data file in $(srcroot)/list and the
100 test PSL data file in $(srcroot)/list/tests. You may also choose
101 to download the latest PSL data file from
102 https://publicsuffix.org/list/public_suffix_list.dat and place it
103 it $(srcroot)/list. Alternatively, specify
104 -Dpsl_file=<path_to_psl_data_file> and/or
105 -Dpsl_testfile=<path_to_test_psl_data_file> when invoking Meson.
106
107Open a Visual Studio command prompt and enter an empty build directory.
108
109Your Python interpreter, Meson executable script and Ninja (if used)
110need to be in your PATH.
111
112Any dependent libraries that are being used should have their headers
113found in paths specified by %INCLUDE% and their .lib files in the
114paths specified by %LIB%.
115
116In the empty build directory, run the following:
117
118meson <path_to_libpsl_git_checkout> --buildtype=... --prefix=<some_prefix> [--backend=vs[2010|2015|2017|2019]]
119
120Please see the Meson documentation for the values accepted by
121--buildtype. --backend=vsXXXX generates the corresponding versions
122of the Visual Studio solution files to build libpsl, which
123will elimnate the need to have the Ninja build tool installed.
124
125When the Meson configuration completes, run 'ninja' or open the
126generated solution files with Visual Studio and build the projects
127to carry out the build. Run 'ninja test' or the test project to
128test the build and run 'ninja install' or 'ninja install' to
129install the build results.
130
131If building with Visual Studio 2008, run the following after running
132'ninja install' in your builddir:
133
134for /r %f in (*.dll.manifest) do if exist $(prefix)\bin\%~nf mt /manifest %f /outputresource:$(prefix)\bin\%~nf;2
135
136for /r %f in (*.exe.manifest) do if exist $(prefix)\bin\%~nf mt /manifest %f /outputresource:$(prefix)\bin\%~nf;1
137
138So that the application manifests get properly embedded.
README.OpenSource
1[
2 {
3 "Name": "libpsl",
4 "License": "MIT",
5 "License File": "LICENSE",
6 "Owner": "lixin113@huawei.com",
7 "Version Number": "0.21.1",
8 "Upstream URL": "https://github.com/rockdaboot/libpsl",
9 "Description": "libpsl - C library to handle the Public Suffix List"
10 }
11]
12
README.md
1[](https://travis-ci.org/rockdaboot/libpsl)
2[](https://scan.coverity.com/projects/rockdaboot-libpsl)
3[](https://coveralls.io/github/rockdaboot/libpsl?branch=master)
4
5Solaris OpenCSW [](https://buildfarm.opencsw.org/buildbot/builders/libpsl-solaris10-amd64)
6[](https://buildfarm.opencsw.org/buildbot/builders/libpsl-solaris10-i386)
7[](https://buildfarm.opencsw.org/buildbot/builders/libpsl-solaris10-sparc)
8[](https://buildfarm.opencsw.org/buildbot/builders/libpsl-solaris10-sparcv9)
9
10
11libpsl - C library to handle the Public Suffix List
12===================================================
13
14A *Public Suffix List* is a collection of Top Level Domains (TLDs) suffixes.
15TLDs include *Global Top Level Domains* (gTLDs) like `.com` and `.net`;
16*Country Top Level Domains* (ccTLDs) like `.de` and `.cn`;
17and *[Brand Top Level Domains](https://icannwiki.org/Brand_TLD)* like `.apple` and `.google`.
18Brand TLDs allows users to register their own top level domain that exist at the same level as ICANN's gTLDs.
19Brand TLDs are sometimes referred to as Vanity Domains.
20
21Browsers, web clients and other user agents can use a public suffix list to:
22
23- avoid privacy-leaking "supercookies"
24- avoid privacy-leaking "super domain" certificates ([see post from Jeffry Walton](https://lists.gnu.org/archive/html/bug-wget/2014-03/msg00093.html))
25- domain highlighting parts of the domain in a user interface
26- sorting domain lists by site
27
28Libpsl...
29
30- has built-in PSL data for fast access (DAWG/DAFSA reduces size from 180kB to ~32kB)
31- allows to load PSL data from files
32- checks if a given domain is a "public suffix"
33- provides immediate cookie domain verification
34- finds the longest public part of a given domain
35- finds the shortest private part of a given domain
36- works with international domains (UTF-8 and IDNA2008 Punycode)
37- is thread-safe
38- handles IDNA2008 UTS#46 (if libicu is available)
39
40Find more information about the Public Suffix List [here](https://publicsuffix.org/).
41
42Download the Public Suffix List [here](https://github.com/publicsuffix/list/blob/master/public_suffix_list.dat).
43
44The original DAFSA code is from the [Chromium Project](https://code.google.com/p/chromium/).
45
46
47API Documentation
48-----------------
49
50You find the current API documentation [here](https://rockdaboot.github.io/libpsl).
51
52
53Quick API example
54-----------------
55
56 #include <stdio.h>
57 #include <libpsl.h>
58
59 int main(int argc, char **argv)
60 {
61 const char *domain = "www.example.com";
62 const char *cookie_domain = ".com";
63 const psl_ctx_t *psl = psl_builtin();
64 int is_public, is_acceptable;
65
66 is_public = psl_is_public_suffix(psl, domain);
67 printf("%s %s a public suffix.\n", domain, is_public ? "is" : "is not");
68
69 is_acceptable = psl_is_cookie_domain_acceptable(psl, domain, cookie_domain);
70 printf("cookie domain '%s' %s acceptable for domain '%s'.\n",
71 cookie_domain, is_acceptable ? "is" : "is not", domain);
72
73 return 0;
74 }
75
76Command Line Tool
77-----------------
78
79Libpsl comes with a tool 'psl' that gives you access to most of the
80library API via command line.
81
82 $ psl --help
83
84prints the usage.
85
86Convert PSL into DAFSA
87----------------------
88
89The [DAFSA](https://en.wikipedia.org/wiki/Deterministic_acyclic_finite_state_automaton) format is a compressed
90representation of strings. Here we use it to reduce the whole PSL to about 32k in size.
91
92Generate `psl.dafsa` from `list/public_suffix_list.dat`
93
94 $ src/psl-make-dafsa --output-format=binary list/public_suffix_list.dat psl.dafsa
95
96Test the result (example)
97
98 $ tools/psl --load-psl-file psl.dafsa aeroclub.aero
99
100License
101-------
102
103Libpsl is made available under the terms of the MIT license.<br>
104See the LICENSE file that accompanies this distribution for the full text of the license.
105
106src/psl-make-dafsa and src/lookup_string_in_fixed_set.c are licensed under the term written in
107src/LICENSE.chromium.
108
109Building from git
110-----------------
111
112You should have python2.7+ installed.
113
114Download project and prepare sources with
115
116 git clone https://github.com/rockdaboot/libpsl
117 ./autogen.sh
118 ./configure
119 make
120 make check
121
122If you prefer a `meson` build
123
124 meson builddir
125 ninja -C builddir
126 ninja -C builddir test
127
128There is also an unofficial MSVC nmake build configuration in `msvc/`. Please
129see README.MSVC.md on building libpsl with Visual Studio via NMake or Meson.
130
131
132Mailing List
133------------
134
135[Mailing List Archive](https://groups.google.com/forum/#!forum/libpsl-bugs)
136
137[Mailing List](https://groups.google.com/forum/#!forum/libpsl-bugs)
138
139To join the mailing list send an email to
140
141libpsl-bugs+subscribe@googlegroups.com
142
143and follow the instructions provided by the answer mail.
144
145Or click [join](https://groups.google.com/forum/#!forum/libpsl-bugs/join).
146
){kind=link}
){kind=link}
){kind=link}