/
installation.xml
2558 lines (2264 loc) · 102 KB
/
installation.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="postgis_installation">
<title>PostGIS Installation</title>
<para>
This chapter details the steps required to install PostGIS.
</para>
<sect1 id="install_short_version">
<title>Short Version</title>
<para>To compile assuming you have all the dependencies in your search path:</para>
<programlisting>tar xvfz postgis-&last_release_version;.tar.gz
cd postgis-&last_release_version;
./configure
make
make install</programlisting>
<para>Once postgis is installed, it needs to be enabled in each individual database you want to use it in.</para>
<note><para>Using the extension enable process is preferred and more user-friendly. To spatially enable your database:</para></note>
<programlisting>
psql -d yourdatabase -c "CREATE EXTENSION postgis;"
-- if you built with raster support and want to install it --
psql -d yourdatabase -c "CREATE EXTENSION postgis_raster;"
-- if you want to install topology support --
psql -d yourdatabase -c "CREATE EXTENSION postgis_topology;"
-- if you built with sfcgal support and want to install it --
psql -d yourdatabase -c "CREATE EXTENSION postgis_sfcgal;"
-- if you want to install tiger geocoder --
psql -d yourdatabase -c "CREATE EXTENSION fuzzystrmatch"
psql -d yourdatabase -c "CREATE EXTENSION postgis_tiger_geocoder;"
-- if you installed with pcre
-- you should have address standardizer extension as well
psql -d yourdatabase -c "CREATE EXTENSION address_standardizer;"
</programlisting>
<para>Please refer to <xref linkend="make_install_postgis_extensions" /> for more details about querying installed/available extensions and upgrading extensions, or switching from a non-extension install to an extension install.</para>
<para>For those who decided for some reason to use a non-extension
based install, here are longer more painful instructions for you:</para>
<para>All the .sql files once installed will be installed in share/contrib/postgis-&last_minor_version; folder
of your PostgreSQL install</para>
<programlisting>createdb yourdatabase
createlang plpgsql yourdatabase
psql -d yourdatabase -f postgis.sql
psql -d yourdatabase -f postgis_comments.sql
psql -d yourdatabase -f spatial_ref_sys.sql
-- if you want to enable topology
psql -d yourdatabase -f topology.sql
psql -d yourdatabase -f topology_comments.sql
-- if you want to enable raster
-- and only if you compiled with raster (GDAL)
psql -d yourdatabase -f rtpostgis.sql
psql -d yourdatabase -f raster_comments.sql
-- if you want to enable sfcgal backend
-- and only if you built with sfcgal support --
psql -d yourdatabase -f sfcgal.sql
psql -d yourdatabase -f sfcgal_comments.sql
</programlisting>
</sect1>
<sect1 id="raster_configuration">
<title>Configuring raster</title>
<para>
If you enabled raster support you may want to read
below how to properly configure it.
</para>
<para>As of PostGIS 2.1.3, out-of-db rasters and all raster drivers are disabled by default. In order to re-enable these, you need to set the following environment variables
<varname>POSTGIS_GDAL_ENABLED_DRIVERS</varname> and <varname>POSTGIS_ENABLE_OUTDB_RASTERS</varname> in the server environment. For PostGIS 2.2, you can use the more cross-platform approach of setting the corresponding <xref linkend="PostGIS_GUC" />.</para>
<para>If you want to enable offline raster:</para>
<programlisting>POSTGIS_ENABLE_OUTDB_RASTERS=1</programlisting>
<para>Any other setting or no setting at all will disable out of db rasters.</para>
<para>In order to enable all GDAL drivers available in your GDAL install, set this environment variable as follows</para>
<programlisting>POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL</programlisting>
<para>If you want to only enable specific drivers, set your environment variable as follows:</para>
<programlisting>POSTGIS_GDAL_ENABLED_DRIVERS="GTiff PNG JPEG GIF XYZ"</programlisting>
<note><para>If you are on windows, do not quote the driver list</para></note>
<para>Setting environment variables varies depending on OS. For PostgreSQL installed on Ubuntu or Debian via apt-postgresql, the preferred way is to
edit <filename>/etc/postgresql/<replaceable>10</replaceable>/<replaceable>main</replaceable>/environment</filename> where 10 refers to version of PostgreSQL and main refers to the cluster.</para>
<para>On windows, if you are running as a service, you can set via System variables which for Windows 7 you can get to by right-clicking on Computer->Properties Advanced System Settings or in explorer navigating to <varname>Control Panel\All Control Panel Items\System</varname>.
Then clicking <emphasis>Advanced System Settings ->Advanced->Environment Variables</emphasis> and adding new system variables.</para>
<para>After you set the environment variables, you'll need to restart your PostgreSQL service for the changes to take effect.</para>
</sect1>
<sect1 id="install_requirements">
<title>Install Requirements</title>
<para>
PostGIS has the following requirements for building and usage:
</para>
<para>
<emphasis role="bold">Required</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
PostgreSQL &min_postgres_version; or higher. A complete installation
of PostgreSQL (including server headers) is required. PostgreSQL
is available from
<ulink url="http://www.postgresql.org">
http://www.postgresql.org
</ulink>
.
</para>
<para>For a full PostgreSQL / PostGIS support matrix and PostGIS/GEOS support matrix refer to
<ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS">http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS</ulink>
</para>
</listitem>
<listitem>
<para>
GNU C compiler (<filename>gcc</filename>). Some other ANSI C compilers
can be used to compile PostGIS, but we find far fewer problems when
compiling with <filename>gcc</filename>.
</para>
</listitem>
<listitem>
<para>
GNU Make (<filename>gmake</filename> or <filename>make</filename>).
For many systems, GNU <filename>make</filename> is the default version
of make. Check the version by invoking <filename>make -v</filename>.
Other versions of <filename>make</filename> may not process the
PostGIS <filename>Makefile</filename> properly.
</para>
</listitem>
<listitem>
<para>
Proj4 reprojection library, version 4.6.0 or greater. Proj4 4.9 or above is needed to take advantage of improved geodetic.
The Proj4 library is used to provide coordinate reprojection support within
PostGIS. Proj4 is available for download from
<ulink url="http://trac.osgeo.org/proj/">
http://trac.osgeo.org/proj/
</ulink>
.
</para>
</listitem>
<listitem>
<para>
GEOS geometry library, version 3.6 or greater, but GEOS 3.7+ is recommended to take full advantage of all the new functions and features. GEOS is available for download from
<ulink url="http://trac.osgeo.org/geos/">
http://trac.osgeo.org/geos/
</ulink>.
</para>
</listitem>
<listitem>
<para>
LibXML2, version 2.5.x or higher. LibXML2 is currently used in some imports
functions (ST_GeomFromGML and ST_GeomFromKML). LibXML2 is available for download from
<ulink url="http://xmlsoft.org/downloads.html">http://xmlsoft.org/downloads.html</ulink>.
</para>
</listitem>
<listitem>
<para>
JSON-C, version 0.9 or higher. JSON-C is currently used to import GeoJSON via the
function ST_GeomFromGeoJson. JSON-C is available for download from
<ulink url="https://github.com/json-c/json-c/releases">https://github.com/json-c/json-c/releases/</ulink>.
</para>
</listitem>
<listitem>
<para>
GDAL, version 1.8 or higher (1.9 or higher is strongly
recommended since some things will not work well or behavior
differently with lower versions). This is required for raster
support.
<ulink url="http://trac.osgeo.org/gdal/wiki/DownloadSource">http://trac.osgeo.org/gdal/wiki/DownloadSource</ulink>.
</para>
</listitem>
<listitem>
<para>
If compiling with PostgreSQL+JIT, LLVM version >=6 is required
<ulink url="https://trac.osgeo.org/postgis/ticket/4125">https://trac.osgeo.org/postgis/ticket/4125</ulink>.
</para>
</listitem>
</itemizedlist>
<para>
<emphasis role="bold">Optional</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
GDAL (pseudo optional) only if you don't want raster
you can leave it out. Also make sure to enable
the drivers you want to use as described in <xref
linkend="raster_configuration"/>.
</para>
</listitem>
<listitem>
<para>
GTK (requires GTK+2.0, 2.8+) to compile the shp2pgsql-gui shape file loader.
<ulink url="http://www.gtk.org/">
http://www.gtk.org/
</ulink>
.
</para>
</listitem>
<listitem>
<para>
SFCGAL, version 1.1 (or higher) could be used to provide additional 2D and 3D advanced analysis functions to PostGIS cf <xref linkend="reference_sfcgal" />. And also allow to use SFCGAL rather than GEOS for some 2D functions provided by both backends (like ST_Intersection or ST_Area, for instance). A PostgreSQL configuration variable <code>postgis.backend</code> allow end user to control which backend he want to use if SFCGAL is installed (GEOS by default). Nota: SFCGAL 1.2 require at least CGAL 4.3 and Boost 1.54 (cf: <ulink url="http://oslandia.github.io/SFCGAL/installation.html">http://oslandia.github.io/SFCGAL/installation.html</ulink>)
<ulink url="https://github.com/Oslandia/SFCGAL">https://github.com/Oslandia/SFCGAL</ulink>.
</para>
</listitem>
<listitem>
<para>
In order to build the <xref linkend="Address_Standardizer" /> you will also need PCRE <ulink url="http://www.pcre.org">http://www.pcre.org</ulink> (which generally is already installed on nix systems). <code>Regex::Assemble</code> perl CPAN package is only needed if you want to rebuild the data encoded in <filename>parseaddress-stcities.h</filename>.
<xref linkend="Address_Standardizer" /> will automatically be built if it detects a PCRE library, or you pass in a valid <varname>--with-pcre-dir=/path/to/pcre</varname> during configure.
</para>
</listitem>
<listitem>
<para>
To enable ST_AsMVT protobuf-c library (for usage) and the protoc-c compiler (for building) are required.
Also, pkg-config is required to verify the correct minimum version of protobuf-c.
See <ulink url="https://github.com/protobuf-c/protobuf-c">protobuf-c</ulink>.
</para>
</listitem>
<listitem>
<para>
CUnit (<filename>CUnit</filename>). This is needed for regression testing. <ulink url="http://cunit.sourceforge.net/">http://cunit.sourceforge.net/</ulink>
</para>
</listitem>
<listitem>
<para>
DocBook (<filename>xsltproc</filename>) is required for building the
documentation. Docbook is available from
<ulink url="http://www.docbook.org/">
http://www.docbook.org/
</ulink>
.
</para>
</listitem>
<listitem>
<para>
DBLatex (<filename>dblatex</filename>) is required for building the
documentation in PDF format. DBLatex is available from
<ulink url="http://dblatex.sourceforge.net/">
http://dblatex.sourceforge.net/
</ulink>
.
</para>
</listitem>
<listitem>
<para>
ImageMagick (<filename>convert</filename>) is required to generate the
images used in the documentation. ImageMagick is available from
<ulink url="http://www.imagemagick.org/">
http://www.imagemagick.org/
</ulink>
.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="install_getting_source">
<title>Getting the Source</title>
<para>
Retrieve the PostGIS source archive from the downloads website
<ulink url="&postgis_download_url;">
&postgis_download_url;
</ulink>
</para>
<programlisting>wget &postgis_download_url;
tar -xvzf postgis-&last_release_version;.tar.gz</programlisting>
<para>
This will create a directory called
<varname>postgis-&last_release_version;</varname> in the current working
directory.
</para>
<para>
Alternatively, checkout the source from the
<ulink url="http://subversion.apache.org/">
svn
</ulink>
repository
<ulink url="https://svn.osgeo.org/postgis/trunk/">
https://svn.osgeo.org/postgis/trunk/
</ulink>
.
</para>
<programlisting>svn checkout https://svn.osgeo.org/postgis/trunk/ postgis-&last_release_version;</programlisting>
<para>
Change into the newly created
<varname>postgis-&last_release_version;</varname> directory to continue
the installation.
</para>
</sect1>
<sect1 id="PGInstall">
<title>Compiling and Install from Source: Detailed</title>
<note>
<para>
Many OS systems now include pre-built packages for PostgreSQL/PostGIS.
In many cases compilation is only necessary if you want the most
bleeding edge versions or you are a package maintainer.
</para>
<para>This section includes general compilation instructions, if you are compiling for Windows etc
or another OS, you may find additional more detailed help at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiInstall">PostGIS User contributed compile guides</ulink> and <ulink url="http://trac.osgeo.org/postgis/wiki/DevWikiMain">PostGIS Dev Wiki</ulink>.</para>
<para>Pre-Built Packages for various OS are listed in <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPackages">PostGIS Pre-built Packages</ulink></para>
<para>If you are a windows user, you can get stable builds via Stackbuilder or <ulink url="https://postgis.net/windows_downloads">PostGIS Windows download site</ulink>
We also have <ulink url="https://postgis.net/windows_downloads">very bleeding-edge windows experimental builds</ulink> that are built usually once or twice a week or whenever anything exciting happens. You can
use these to experiment with the in progress releases of PostGIS</para>
</note>
<para>
The PostGIS module is an extension to the PostgreSQL backend server. As
such, PostGIS &last_release_version; <emphasis>requires</emphasis> full
PostgreSQL server headers access in order to compile. It can be built
against PostgreSQL versions &min_postgres_version; or higher. Earlier
versions of PostgreSQL are <emphasis>not</emphasis> supported.
</para>
<para>
Refer to the PostgreSQL installation guides if you haven't already
installed PostgreSQL.
<ulink url="http://www.postgresql.org">
http://www.postgresql.org
</ulink>
.
</para>
<note>
<para>
For GEOS functionality, when you install PostgresSQL you may need to
explicitly link PostgreSQL against the standard C++ library:
</para>
<programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>
<para>
This is a workaround for bogus C++ exceptions interaction with older
development tools. If you experience weird problems (backend
unexpectedly closed or similar things) try this trick. This will require
recompiling your PostgreSQL from scratch, of course.
</para>
</note>
<para>
The following steps outline the configuration and compilation of the
PostGIS source. They are written for Linux users and will not work on
Windows or Mac.
</para>
<sect2 id="installation_configuration">
<title>Configuration</title>
<para>
As with most linux installations, the first step is to generate the
Makefile that will be used to build the source code. This is done by
running the shell script
</para>
<para>
<command>./configure</command>
</para>
<para>
With no additional parameters, this command will attempt to
automatically locate the required components and libraries needed to
build the PostGIS source code on your system. Although this is the most
common usage of <command>./configure</command>, the script accepts
several parameters for those who have the required libraries and
programs in non-standard locations.
</para>
<para>
The following list shows only the most commonly used parameters. For a
complete list, use the <command>--help</command> or
<command>--help=short</command> parameters.
</para>
<variablelist>
<varlistentry>
<term><command>--with-library-minor-version</command></term>
<listitem>
<para>Starting with PostGIS 3.0, the library files generated by default will no longer have the minor version
as part of the file name. This means all PostGIS 3 libs will end in <code>postgis-3</code>.
This was done to make pg_upgrade easier, with downside that you can only install
one version PostGIS 3 series in your server.
To get the old behavior of file including the minor version: e.g. <code>postgis-3.0</code>
add this switch to your configure statement.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--prefix=PREFIX</command></term>
<listitem>
<para>
This is the location the PostGIS loader executables and shared libs will be installed.
By default, this location is the same as the
detected PostgreSQL installation.
</para>
<caution>
<para>
This parameter is currently broken, as the package will only
install into the PostgreSQL installation directory. Visit
<ulink url="http://trac.osgeo.org/postgis/ticket/635">
http://trac.osgeo.org/postgis/ticket/635
</ulink>
to track this bug.
</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-pgconfig=FILE</command></term>
<listitem>
<para>
PostgreSQL provides a utility called <command>pg_config</command>
to enable extensions like PostGIS to locate the PostgreSQL
installation directory. Use this parameter
(<command>--with-pgconfig=/path/to/pg_config</command>) to
manually specify a particular PostgreSQL installation that PostGIS
will build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-gdalconfig=FILE</command></term>
<listitem>
<para>
GDAL, a required library, provides functionality needed for raster support
<command>gdal-config</command> to enable software installations to
locate the GDAL installation directory. Use this parameter
(<command>--with-gdalconfig=/path/to/gdal-config</command>) to
manually specify a particular GDAL installation that PostGIS will
build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-geosconfig=FILE</command></term>
<listitem>
<para>
GEOS, a required geometry library, provides a utility called
<command>geos-config</command> to enable software installations to
locate the GEOS installation directory. Use this parameter
(<command>--with-geosconfig=/path/to/geos-config</command>) to
manually specify a particular GEOS installation that PostGIS will
build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-xml2config=FILE</command></term>
<listitem>
<para>
LibXML is the library required for doing GeomFromKML/GML processes.
It normally is found if you have libxml installed, but if not or you want
a specific version used, you'll need to point PostGIS at a specific
<filename>xml2-config</filename> confi file to enable software installations to
locate the LibXML installation directory. Use this parameter
(<command>>--with-xml2config=/path/to/xml2-config</command>) to
manually specify a particular LibXML installation that PostGIS will
build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-projdir=DIR</command></term>
<listitem>
<para>
Proj4 is a reprojection library required by PostGIS. Use this
parameter (<command>--with-projdir=/path/to/projdir</command>) to
manually specify a particular Proj4 installation directory that
PostGIS will build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-libiconv=DIR</command></term>
<listitem>
<para>
Directory where iconv is installed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-jsondir=DIR</command></term>
<listitem>
<para>
<ulink url="http://oss.metaparadigm.com/json-c/">JSON-C</ulink> is an MIT-licensed JSON library required by PostGIS ST_GeomFromJSON support. Use this
parameter (<command>--with-jsondir=/path/to/jsondir</command>) to
manually specify a particular JSON-C installation directory that
PostGIS will build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-pcredir=DIR</command></term>
<listitem>
<para>
<ulink url="http://www.pcre.org/">PCRE</ulink> is an BSD-licensed Perl Compatible Regular Expression library required by address_standardizer extension. Use this
parameter (<command>--with-pcredir=/path/to/pcredir</command>) to
manually specify a particular PCRE installation directory that
PostGIS will build against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-gui</command></term>
<listitem>
<para>
Compile the data import GUI (requires GTK+2.0). This will create shp2pgsql-gui graphical interface
to shp2pgsql.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--without-raster</command></term>
<listitem>
<para>
Compile without raster support.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--without-topology</command></term>
<listitem>
<para>
Disable topology support. There is no corresponding library
as all logic needed for topology is in postgis-&last_release_version; library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-gettext=no</command></term>
<listitem>
<para>
By default PostGIS will try to detect gettext support and compile with it, however if you run into incompatibility issues that
cause breakage of loader, you can disable it entirely with this command. Refer to ticket <ulink url="http://trac.osgeo.org/postgis/ticket/748">http://trac.osgeo.org/postgis/ticket/748</ulink> for an example issue solved by configuring with this.
NOTE: that you aren't missing much by turning this off. This is used for international help/label support for the GUI loader which is not yet documented
and still experimental.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>--with-sfcgal=PATH</command></term>
<listitem>
<para>
By default PostGIS will not install with sfcgal support without this switch.
<varname>PATH</varname> is an optional argument that allows to specify an alternate PATH to sfcgal-config.
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
If you obtained PostGIS from the
<ulink url="https://trac.osgeo.org/postgis/wiki/CodeRepository">
code repository
</ulink>
, the first step is really to run the script
</para>
<para>
<command>./autogen.sh</command>
</para>
<para>
This script will generate the <command>configure</command> script that
in turn is used to customize the installation of PostGIS.
</para>
<para>
If you instead obtained PostGIS as a tarball, running
<command>./autogen.sh</command> is not necessary as
<command>configure</command> has already been generated.
</para>
</note>
</sect2>
<sect2>
<title>Building</title>
<para>
Once the Makefile has been generated, building PostGIS is as simple as
running
</para>
<para>
<command>make</command>
</para>
<para>
The last line of the output should be "<code>PostGIS was built
successfully. Ready to install.</code>"
</para>
<para>
As of PostGIS v1.4.0, all the functions have comments generated from the
documentation. If you wish to install these comments into your spatial
databases later, run the command which requires docbook. The postgis_comments.sql and other
package comments files raster_comments.sql, topology_comments.sql are
also packaged in the tar.gz distribution in the doc folder so no need to make comments
if installing from the tar ball. Comments are also included as part of the CREATE EXTENSION install.
</para>
<para>
<command>make comments</command>
</para>
<para>
Introduced in PostGIS 2.0. This generates html cheat sheets suitable for quick reference or for student handouts.
This requires xsltproc to build and will generate 4 files in doc folder <filename>topology_cheatsheet.html</filename>, <filename>tiger_geocoder_cheatsheet.html</filename>,
<filename>raster_cheatsheet.html</filename>, <filename>postgis_cheatsheet.html</filename>
</para>
<para>You can download some pre-built ones available in html and pdf from <ulink url="http://www.postgis.us/study_guides">PostGIS / PostgreSQL Study Guides</ulink></para>
<para>
<command>make cheatsheets</command>
</para>
</sect2>
<sect2 id="make_install_postgis_extensions">
<title>Building PostGIS Extensions and Deploying them</title>
<para>
The PostGIS extensions are built and installed automatically if you are using PostgreSQL 9.1+.
</para>
<para>If you are building from source repository, you need to build the function descriptions first. These get built if you have docbook installed. You can also manually build with the statement:
</para>
<para>
<command>make comments</command>
</para>
<para>Building the comments is not necessary if you are building from a release tar ball since these are packaged pre-built with the tar ball already.</para>
<para>The extensions should automatically build as part of the make install process. You can if needed build from the extensions
folders or copy files if you need them on a different server. </para>
<programlisting>cd extensions
cd postgis
make clean
make
export PGUSER=postgres #overwrite psql variables
make check #to test before install
make install
# to test extensions
make check RUNTESTFLAGS=--extension</programlisting>
<note><para><code>make check</code> uses psql to run tests and as such can use psql environment variables.
Common ones useful to override are <varname>PGUSER</varname>,<varname>PGPORT</varname>, and <varname>PGHOST</varname>. Refer to <ulink url="https://www.postgresql.org/docs/current/libpq-envars.html">psql environment variables</ulink> </para></note>
<para>The extension files will always be the same for the same version of PostGIS and PostgreSQL regardless of OS, so it is fine to copy over the extension files from one OS to another as long as you
have the PostGIS binaries already installed on your servers. </para>
<para>If you want to install the extensions manually on a separate server different from your development,
You need to copy the following files from the extensions folder into the <filename>PostgreSQL / share / extension</filename> folder
of your PostgreSQL install as well as the needed binaries for regular PostGIS if you don't have them already on the server.
</para>
<itemizedlist>
<listitem>
<para>
These are the control files that denote information such as the version of the extension to install if not specified.
<filename>postgis.control, postgis_topology.control</filename>.
</para>
</listitem>
<listitem>
<para>
All the files in the /sql folder of each extension. Note that these need to be copied to the root of the PostgreSQL share/extension folder
<filename>extensions/postgis/sql/*.sql</filename>, <filename>extensions/postgis_topology/sql/*.sql</filename>
</para>
</listitem>
</itemizedlist>
<para>Once you do that, you should see <varname>postgis</varname>, <varname>postgis_topology</varname> as available extensions in PgAdmin -> extensions.</para>
<para>If you are using psql, you can verify that the extensions are installed by running this query:</para>
<programlisting>SELECT name, default_version,installed_version
FROM pg_available_extensions WHERE name LIKE 'postgis%' or name LIKE 'address%';
name | default_version | installed_version
------------------------------+-----------------+-------------------
address_standardizer | &last_release_version; | &last_release_version;
address_standardizer_data_us | &last_release_version; | &last_release_version;
postgis | &last_release_version; | &last_release_version;
postgis_raster | &last_release_version; | &last_release_version;
postgis_sfcgal | &last_release_version; |
postgis_tiger_geocoder | &last_release_version; | &last_release_version;
postgis_topology | &last_release_version; |
(6 rows)</programlisting>
<para>If you have the extension installed in the database you are querying, you'll see mention in the <varname>installed_version</varname> column.
If you get no records back, it means you don't have postgis extensions installed on the server at all. PgAdmin III 1.14+ will also provide this information
in the <varname>extensions</varname> section of the database browser tree and will even allow upgrade or uninstall by right-clicking.</para>
<para>If you have the extensions available, you can install postgis extension in your database of choice by either using pgAdmin extension interface or running these sql commands:</para>
<programlisting>CREATE EXTENSION postgis;
CREATE EXTENSION postgis_raster;
CREATE EXTENSION postgis_sfcgal;
CREATE EXTENSION fuzzystrmatch; --needed for postgis_tiger_geocoder
--optional used by postgis_tiger_geocoder, or can be used standalone
CREATE EXTENSION address_standardizer;
CREATE EXTENSION address_standardizer_data_us;
CREATE EXTENSION postgis_tiger_geocoder;
CREATE EXTENSION postgis_topology;</programlisting>
<para>In psql you can use to see what versions you have installed and also what schema they are installed. </para>
<programlisting>\connect mygisdb
\x
\dx postgis*</programlisting>
<screen>List of installed extensions
-[ RECORD 1 ]-------------------------------------------------
Name | postgis
Version | &last_release_version;
Schema | public
Description | PostGIS geometry, geography, and raster spat..
-[ RECORD 2 ]-------------------------------------------------
Name | postgis_raster
Version | 3.0.0dev
Schema | public
Description | PostGIS raster types and functions
-[ RECORD 3 ]-------------------------------------------------
Name | postgis_tiger_geocoder
Version | &last_release_version;
Schema | tiger
Description | PostGIS tiger geocoder and reverse geocoder
-[ RECORD 4 ]-------------------------------------------------
Name | postgis_topology
Version | &last_release_version;
Schema | topology
Description | PostGIS topology spatial types and functions</screen>
<warning><para>Extension tables <varname>spatial_ref_sys</varname>, <varname>layer</varname>, <varname>topology</varname> can not be explicitly backed up. They can only
be backed up when the respective <varname>postgis</varname> or <varname>postgis_topology</varname> extension is backed up, which only seems to happen when you backup the whole database.
As of PostGIS 2.0.1, only srid records not packaged with PostGIS are backed up when the database is backed up so don't go around changing srids we package and expect your changes to be there. Put in a ticket if you find an issue. The structures of extension tables are never backed up since they are created with <code>CREATE EXTENSION</code>
and assumed to be the same for a given version of an extension. These behaviors are built into the current PostgreSQL extension model, so nothing we can do about it.</para></warning>
<para>If you installed &last_release_version;, without using our
wonderful extension system, you can change it to be extension based by
running the below commands to package the functions in their respective extension.
</para>
<programlisting>
CREATE EXTENSION postgis FROM unpackaged;
CREATE EXTENSION postgis_raster FROM unpackaged;
CREATE EXTENSION postgis_topology FROM unpackaged;
CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;
</programlisting>
</sect2>
<sect2>
<title>Testing</title>
<para>
If you wish to test the PostGIS build, run
</para>
<para>
<command>make check</command>
</para>
<para>
The above command will run through various checks and regression tests
using the generated library against an actual PostgreSQL database.
</para>
<note>
<para>
If you configured PostGIS using non-standard PostgreSQL, GEOS, or
Proj4 locations, you may need to add their library locations to the
<varname>LD_LIBRARY_PATH</varname> environment variable.
</para>
</note>
<caution>
<para>
Currently, the <command>make check</command> relies on the
<code>PATH</code> and <code>PGPORT</code> environment variables when
performing the checks - it does <emphasis>not</emphasis> use the
PostgreSQL version that may have been specified using the
configuration parameter <command>--with-pgconfig</command>. So make
sure to modify your PATH to match the detected PostgreSQL installation
during configuration or be prepared to deal with the impending
headaches.
</para>
</caution>
<para>
If successful, the output of the test should be similar to the
following:
</para>
<programlisting>
CUnit - A unit testing framework for C - Version 2.1-2
http://cunit.sourceforge.net/
Suite: algorithm
Test: test_lw_segment_side ...passed
Test: test_lw_segment_intersects ...passed
Test: test_lwline_crossing_short_lines ...passed
Test: test_lwline_crossing_long_lines ...passed
Test: test_lwline_crossing_bugs ...passed
Test: test_lwpoint_set_ordinate ...passed
Test: test_lwpoint_get_ordinate ...passed
Test: test_point_interpolate ...passed
Test: test_lwline_interpolate_points ...passed
Test: test_lwline_clip ...passed
Test: test_lwpoly_clip ...passed
Test: test_lwtriangle_clip ...passed
Test: test_lwline_clip_big ...passed
Test: test_lwmline_clip ...passed
Test: test_geohash_point ...passed
Test: test_geohash_precision ...passed
Test: test_geohash ...passed
Test: test_geohash_point_as_int ...passed
Test: test_isclosed ...passed
Test: test_lwgeom_simplify ...passed
Test: test_lw_arc_center ...passed
Test: test_point_density ...passed
Test: test_kmeans ...passed
Test: test_median_handles_3d_correctly ...passed
Test: test_median_robustness ...passed
Test: test_lwpoly_construct_circle ...passed
Test: test_trim_bits ...passed
Test: test_lwgeom_remove_repeated_points ...passed
Suite: buildarea
Test: buildarea1 ...passed
Test: buildarea2 ...passed
Test: buildarea3 ...passed
Test: buildarea4 ...passed
Test: buildarea4b ...passed
Test: buildarea5 ...passed
Test: buildarea6 ...passed
Test: buildarea7 ...passed
Suite: geometry_clean
Test: test_lwgeom_make_valid ...passed
Suite: clip_by_rectangle
Test: test_lwgeom_clip_by_rect ...passed
Suite: force_sfs
Test: test_sfs_11 ...passed
Test: test_sfs_12 ...passed
Test: test_sqlmm ...passed
Suite: geodetic
Test: test_sphere_direction ...passed
Test: test_sphere_project ...passed
Test: test_lwgeom_area_sphere ...passed
Test: test_gbox_from_spherical_coordinates ...passed
Test: test_gserialized_get_gbox_geocentric ...passed
Test: test_clairaut ...passed
Test: test_edge_intersection ...passed
Test: test_edge_intersects ...passed
Test: test_edge_distance_to_point ...passed
Test: test_edge_distance_to_edge ...passed
Test: test_lwgeom_distance_sphere ...passed
Test: test_lwgeom_check_geodetic ...passed
Test: test_gserialized_from_lwgeom ...passed
Test: test_spheroid_distance ...passed
Test: test_spheroid_area ...passed
Test: test_lwpoly_covers_point2d ...passed
Test: test_gbox_utils ...passed
Test: test_vector_angle ...passed
Test: test_vector_rotate ...passed
Test: test_lwgeom_segmentize_sphere ...passed
Test: test_ptarray_contains_point_sphere ...passed
Test: test_ptarray_contains_point_sphere_iowa ...passed
Test: test_gbox_to_string_truncated ...passed
Suite: geos
Test: test_geos_noop ...passed
Test: test_geos_subdivide ...passed
Test: test_geos_linemerge ...passed
Test: test_geos_offsetcurve ...passed
Test: test_geos_offsetcurve_crash ...passed
Test: test_geos_makevalid ...passed
Suite: clustering
Test: basic_test ...passed
Test: nonsequential_test ...passed
Test: basic_distance_test ...passed
Test: single_input_test ...passed
Test: empty_inputs_test ...passed
Test: multipoint_test ...passed
Test: dbscan_test ...passed
Test: dbscan_test_3612a ...passed
Test: dbscan_test_3612b ...passed
Test: dbscan_test_3612c ...passed
Suite: clustering_unionfind
Test: test_unionfind_create ...passed
Test: test_unionfind_union ...passed
Test: test_unionfind_ordered_by_cluster ...passed
Test: test_unionfind_path_compression ...passed
Test: test_unionfind_collapse_cluster_ids ...passed
Suite: homogenize
Test: test_coll_point ...passed
Test: test_coll_line ...passed
Test: test_coll_poly ...passed
Test: test_coll_coll ...passed
Test: test_geom ...passed
Test: test_coll_curve ...passed
Suite: encoded_polyline_input
Test: in_encoded_polyline_test_geoms ...passed
Test: in_encoded_polyline_test_precision ...passed
Suite: geojson_input
Test: in_geojson_test_srid ...passed
Test: in_geojson_test_bbox ...passed
Test: in_geojson_test_geoms ...passed
Suite: iterator
Test: test_point_count ...passed
Test: test_ordering ...passed
Test: test_modification ...passed
Test: test_mixed_rw_access ...passed
Test: test_cannot_modify_read_only ...passed
Test: test_no_memory_leaked_when_iterator_is_partially_used ...passed
Suite: twkb_input
Test: test_twkb_in_point ...passed
Test: test_twkb_in_linestring ...passed
Test: test_twkb_in_polygon ...passed
Test: test_twkb_in_multipoint ...passed
Test: test_twkb_in_multilinestring ...passed
Test: test_twkb_in_multipolygon ...passed
Test: test_twkb_in_collection ...passed
Test: test_twkb_in_precision ...passed
Suite: serialization/deserialization
Test: test_typmod_macros ...passed
Test: test_flags_macros ...passed
Test: test_serialized_srid ...NOTICE: SRID value -3005 converted to the officially unknown SRID value 0
passed
Test: test_gserialized_from_lwgeom_size ...passed
Test: test_gbox_serialized_size ...passed
Test: test_lwgeom_from_gserialized ...passed
Test: test_lwgeom_count_vertices ...passed
Test: test_on_gser_lwgeom_count_vertices ...passed
Test: test_geometry_type_from_string ...passed
Test: test_lwcollection_extract ...passed
Test: test_lwgeom_free ...passed
Test: test_lwgeom_swap_ordinates ...passed
Test: test_f2d ...passed
Test: test_lwgeom_clone ...passed
Test: test_lwgeom_force_clockwise ...passed
Test: test_lwgeom_calculate_gbox ...passed
Test: test_lwgeom_is_empty ...passed
Test: test_lwgeom_same ...passed
Test: test_lwline_from_lwmpoint ...passed
Test: test_lwgeom_as_curve ...passed
Test: test_lwgeom_scale ...passed
Test: test_gserialized_is_empty ...passed
Test: test_gserialized_peek_gbox_p_no_box_when_empty ...passed
Test: test_gserialized_peek_gbox_p_gets_correct_box ...passed
Test: test_gserialized_peek_gbox_p_fails_for_unsupported_cases ...passed
Test: test_gbox_same_2d ...passed
Test: test_signum_macro ...passed
Suite: lwstroke
Test: test_lwcurve_linearize ...passed
Test: test_unstroke ...passed
Suite: measures
Test: test_mindistance2d_tolerance ...passed
Test: test_mindistance3d_tolerance ...NOTICE: One or both of the geometries is missing z-value. The unknown z-value will be regarded as "any value"
passed
Test: test_rect_tree_contains_point ...passed
Test: test_rect_tree_intersects_tree ...passed
Test: test_lwgeom_segmentize2d ...NOTICE: ptarray.c:445 - ptarray_segmentize2d: Too many segments required (1.000000e+101)