diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc index 45c69e7d3b..3766f55be2 100644 --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -1,4637 +1,4637 @@ --- title: Chapter 6. Special Considerations prev: books/porters-handbook/makefiles next: books/porters-handbook/flavors description: Special considerations when creating a new FreeBSD Port tags: ["special considerations", "Handling Symbolic Links", "Bundled Libraries"] --- [[special]] = Special Considerations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] This section explains the most common things to consider when creating a port. [[staging]] == Staging [.filename]#bsd.port.mk# expects ports to work with a "stage directory". This means that a port must not install files directly to the regular destination directories (that is, under `PREFIX`, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, `STAGEDIR`. A package is created from the stage directory and then installed on the system. Automake tools refer to this concept as `DESTDIR`, but in FreeBSD, `DESTDIR` has a different meaning (see crossref:testing[porting-prefix,`PREFIX` and `DESTDIR`]). [NOTE] ==== No port _really_ needs to be root. It can mostly be avoided by using crossref:uses[uses-uidfix,`USES=uidfix`]. If the port still runs commands like man:chown[8], man:chgrp[1], or forces owner or group with man:install[1] then use crossref:uses[uses-fakeroot,`USES=fakeroot`] to fake those calls. Some patching of the port's [.filename]#Makefiles# will be needed. ==== Meta ports, or ports that do not install files themselves but only depend on other ports, must avoid needlessly extracting the man:mtree[8] to the stage directory. This is the basic directory layout of the package, and these empty directories will be seen as orphans. To prevent man:mtree[8] extraction, add this line: [.programlisting] .... NO_MTREE= yes .... [TIP] ==== Metaports should use <>. It sets up defaults for ports that do not fetch, build, or install anything. ==== Staging is enabled by prepending `STAGEDIR` to paths used in the `pre-install`, `do-install`, and `post-install` targets (see the examples through the book). Typically, this includes `PREFIX`, `ETCDIR`, `DATADIR`, `EXAMPLESDIR`, `MANPREFIX`, `DOCSDIR`, and so on. Directories should be created as part of the `post-install` target. Avoid using absolute paths whenever possible. [TIP] ==== Ports that install kernel modules must prepend `STAGEDIR` to their destination, by default [.filename]#/boot/modules#. ==== [[staging-symlink]] === Handling Symbolic Links When creating a symbolic link, relative ones are strongly recommended. Use `${RLN}` to create relative symbolic links. It uses man:install[1] under the hood to automatically figure out the relative link to create. [[staging-ex1]] .Create Relative Symbolic Links Automatically [example] ==== `${RLN}` uses man:install[1]'s relative symbolic feature which frees the porter of computing the relative path. [.programlisting] .... ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so ${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar ${RLN} ${STAGEDIR}/var/cache/foo ${STAGEDIR}${PREFIX}/share/foo .... Will generate: [source,shell] .... % ls -lF ${STAGEDIR}${PREFIX}/lib lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42 -rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42* % ls -lF ${STAGEDIR}${PREFIX}/bin lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar % ls -lF ${STAGEDIRDIR}${PREFIX}/share lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> ../../../var/cache/foo .... ==== [[bundled-libs]] == Bundled Libraries This section explains why bundled dependencies are considered bad and what to do about them. [[bundled-libs-why-bad]] === Why Bundled Libraries Are Bad Some software requires the porter to locate third-party libraries and add the required dependencies to the port. Other software bundles all necessary libraries into the distribution file. The second approach seems easier at first, but there are some serious drawbacks: This list is loosely based on the https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries[Fedora] and http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies[Gentoo] wikis, both licensed under the http://creativecommons.org/licenses/by-sa/3.0/[CC-BY-SA 3.0] license. Security:: If vulnerabilities are found in the upstream library and fixed there, they might not be fixed in the library bundled with the port. One reason could be that the author is not aware of the problem. This means that the porter must fix them, or upgrade to a non-vulnerable version, and send a patch to the author. This all takes time, which results in software being vulnerable longer than necessary. This in turn makes it harder to coordinate a fix without unnecessarily leaking information about the vulnerability. Bugs:: This problem is similar to the problem with security in the last paragraph, but generally less severe. Forking:: It is easier for the author to fork the upstream library once it is bundled. While convenient on first sight, it means that the code diverges from upstream making it harder to address security or other problems with the software. A reason for this is that patching becomes harder. + Another problem of forking is that because code diverges from upstream, bugs get solved over and over again instead of just once at a central location. This defeats the idea of open source software in the first place. Symbol collision:: When a library is installed on the system, it might collide with the bundled version. This can cause immediate errors at compile or link time. It can also cause errors when running the program which might be harder to track down. The latter problem could be caused because the versions of the two libraries are incompatible. Licensing:: When bundling projects from different sources, license issues can arise more easily, especially when licenses are incompatible. Waste of resources:: Bundled libraries waste resources on several levels. It takes longer to build the actual application, especially if these libraries are already present on the system. At run-time, they can take up unnecessary memory when the system-wide library is already loaded by one program and the bundled library is loaded by another program. Waste of effort:: When a library needs patches for FreeBSD, these patches have to be duplicated again in the bundled library. This wastes developer time because the patches might not apply cleanly. It can also be hard to notice that these patches are required in the first place. [[bundled-libs-practices]] === What to do About Bundled Libraries Whenever possible, use the unbundled version of the library by adding a `LIB_DEPENDS` to the port. If such a port does not exist yet, consider creating it. Only use bundled libraries if the upstream has a good track record on security and using unbundled versions leads to overly complex patches. [NOTE] ==== In some very special cases, for example emulators, like Wine, a port has to bundle libraries, because they are in a different architecture, or they have been modified to fit the software's use. In that case, those libraries should not be exposed to other ports for linking. Add `BUNDLE_LIBS=yes` to the port's [.filename]#Makefile#. This will tell man:pkg[8] to not compute provided libraries. Always ask the {portmgr} before adding this to a port. ==== [[porting-shlibs]] == Shared Libraries If the port installs one or more shared libraries, define a `USE_LDCONFIG` make variable, which will instruct a [.filename]#bsd.port.mk# to run `${LDCONFIG} -m` on the directory where the new library is installed (usually [.filename]#PREFIX/lib#) during `post-install` target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate `@exec /sbin/ldconfig -m` and `@unexec /sbin/ldconfig -R` pair into [.filename]#pkg-plist#, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there. [.programlisting] .... USE_LDCONFIG= yes .... The default directory can be overridden by setting `USE_LDCONFIG` to a list of directories into which shared libraries are to be installed. For example, if the port installs shared libraries into [.filename]#PREFIX/lib/foo# and [.filename]#PREFIX/lib/bar# use this in [.filename]#Makefile#: [.programlisting] .... USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar .... Please double-check, often this is not necessary at all or can be avoided through `-rpath` or setting `LD_RUN_PATH` during linking (see package:lang/mosml[] for an example), or through a shell-wrapper which sets `LD_LIBRARY_PATH` before invoking the binary, like package:www/seamonkey[] does. When installing 32-bit libraries on a 64-bit system, use `USE_LDCONFIG32` instead. If the software uses <>, and specifically `libtool`, add crossref:uses[uses-libtool,`USES=libtool`]. When the major library version number increments in the update to the new port version, all other ports that link to the affected library must have their `PORTREVISION` incremented, to force recompilation with the new library version. [[porting-restrictions]] == Ports with Distribution Restrictions or Legal Concerns Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on. [IMPORTANT] ==== It is the responsibility of a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the {freebsd-ports}. ==== In situations like this, the variables described in the next sections can be set. [[porting-restrictions-no_package]] === `NO_PACKAGE` This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources. However, the port's `DISTFILES` may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless `NO_CDROM` is set as well. If the binary package is not generally useful, and the application must always be compiled from the source code, use `NO_PACKAGE`. For example, if the application has configuration information that is site specific hard coded into it at compile time, set `NO_PACKAGE`. Set `NO_PACKAGE` to a string describing the reason why the package cannot be generated. [[porting-restrictions-no_cdrom]] === `NO_CDROM` This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's `DISTFILES` onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's `DISTFILES` will still be available via FTP/HTTP. If this variable is set along with `NO_PACKAGE`, then only the port's `DISTFILES` will be available, and only via FTP/HTTP. Set `NO_CDROM` to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, use this if the port's license is for "non-commercial" use only. [[porting-restrictions-nofetchfiles]] === `NOFETCHFILES` Files defined in `NOFETCHFILES` are not fetchable from any of `MASTER_SITES`. An example of such a file is when the file is supplied on CD-ROM by the vendor. Tools which check for the availability of these files on `MASTER_SITES` have to ignore these files and not report about them. [[porting-restrictions-restricted]] === `RESTRICTED` Set this variable alone if the application's license permits neither mirroring the application's `DISTFILES` nor distributing the binary package in any way. Do not set `NO_CDROM` or `NO_PACKAGE` along with `RESTRICTED`, since the latter variable implies the former ones. Set `RESTRICTED` to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the `DISTFILES`, possibly after registering for the software or agreeing to accept the terms of an EULA. [[porting-restrictions-restricted_files]] === `RESTRICTED_FILES` When `RESTRICTED` or `NO_CDROM` is set, this variable defaults to `${DISTFILES} ${PATCHFILES}`, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them. [[porting-restrictions-legal_text]] === `LEGAL_TEXT` If the port has legal concerns not addressed by the above variables, set `LEGAL_TEXT` to a string explaining the concern. For example, if special permission was obtained for FreeBSD to redistribute the binary, this variable must indicate so. [[porting-restrictions-legal]] === [.filename]#/usr/ports/LEGAL# and `LEGAL` A port which sets any of the above variables must also be added to [.filename]#/usr/ports/LEGAL#. The first column is a glob which matches the restricted distfiles. The second column is the port's origin. The third column is the output of `make -VLEGAL`. [[porting-restrictions-examples]] === Examples The preferred way to state "the distfiles for this port must be fetched manually" is as follows: [.programlisting] .... .if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) IGNORE= may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR} .endif .... This both informs the user, and sets the proper metadata on the user's machine for use by automated programs. Note that this stanza must be preceded by an inclusion of [.filename]#bsd.port.pre.mk#. [[building]] == Building Mechanisms [[parallel-builds]] === Building Ports in Parallel The FreeBSD ports framework supports parallel building using multiple `make` sub-processes, which allows SMP systems to utilize all of their available CPU power, allowing port builds to be faster and more effective. This is achieved by passing `-jX` flag to man:make[1] running on vendor code. This is the default build behavior of ports. Unfortunately, not all ports handle parallel building well and it may be required to explicitly disable this feature by adding the `MAKE_JOBS_UNSAFE=yes` variable. It is used when a port is known to be broken with `-jX` due to race conditions causing intermittent build failures. [IMPORTANT] ==== When setting `MAKE_JOBS_UNSAFE`, it is very important to explain either with a comment in the [.filename]#Makefile#, or at least in the commit message, _why_ the port does not build when enabling. Otherwise, it is almost impossible to either fix the problem, or test if it has been fixed when committing an update at a later date. ==== [[using-make]] === `make`, `gmake`, and `imake` Several differing `make` implementations exist. Ported software often requires a particular implementation, like GNU`make`, known in FreeBSD as `gmake`. If the port uses GNU make, add `gmake` to `USES`. `MAKE_CMD` can be used to reference the specific command configured by the `USES` setting in the port's [.filename]#Makefile#. Only use `MAKE_CMD` within the application [.filename]##Makefile##s in `WRKSRC` to call the `make` implementation expected by the ported software. If the port is an X application that uses imake to create [.filename]##Makefile##s from [.filename]##Imakefile##s, set `USES= imake`. See the crossref:uses[uses-imake,`USES=imake`] section of crossref:uses[uses,Using `USES` Macros] for more details. If the port's source [.filename]#Makefile# has something other than `all` as the main build target, set `ALL_TARGET` accordingly. The same goes for `install` and `INSTALL_TARGET`. [[using-configure]] === `configure` Script If the port uses the `configure` script to generate [.filename]#Makefile# from [.filename]#Makefile.in#, set `GNU_CONFIGURE=yes`. To give extra arguments to the `configure` script (the default argument is `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}`), set those extra arguments in `CONFIGURE_ARGS`. Extra environment variables can be passed using `CONFIGURE_ENV`. [[using-configure-variables]] .Variables for Ports That Use `configure` [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`GNU_CONFIGURE` |The port uses `configure` script to prepare build. |`HAS_CONFIGURE` |Same as `GNU_CONFIGURE`, except default configure target is not added to `CONFIGURE_ARGS`. |`CONFIGURE_ARGS` |Additional arguments passed to `configure` script. |`CONFIGURE_ENV` |Additional environment variables to be set for `configure` script run. |`CONFIGURE_TARGET` |Override default configure target. Default value is `${MACHINE_ARCH}-portbld-freebsd${OSREL}`. |=== [[using-cmake]] === Using `cmake` For ports that use CMake, define `USES= cmake`. [[using-cmake-variables]] .Variables for Ports That Use `cmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`CMAKE_ARGS` |Port specific CMake flags to be passed to the `cmake` binary. |`CMAKE_ON` |For each entry in `CMAKE_ON`, an enabled boolean value is added to `CMAKE_ARGS`. See <>. |`CMAKE_OFF` |For each entry in `CMAKE_OFF`, a disabled boolean value is added to `CMAKE_ARGS`. See <>. |`CMAKE_BUILD_TYPE` |Type of build (CMake predefined build profiles). Default is `Release`, or `Debug` if `WITH_DEBUG` is set. |`CMAKE_SOURCE_PATH` |Path to the source directory. Default is `${WRKSRC}`. |`CONFIGURE_ENV` |Additional environment variables to be set for the `cmake` binary. |=== [[using-cmake-user-variables]] .Variables the Users Can Define for `cmake` Builds [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`CMAKE_NOCOLOR` |Disables color build output. Default not set, unless `BATCH` or `PACKAGE_BUILDING` are set. |=== CMake supports these build profiles: `Debug`, `Release`, `RelWithDebInfo` and `MinSizeRel`. `Debug` and `Release` profiles respect system `\*FLAGS`, `RelWithDebInfo` and `MinSizeRel` will set `CFLAGS` to `-O2 -g` and `-Os -DNDEBUG` correspondingly. The lower-cased value of `CMAKE_BUILD_TYPE` is exported to `PLIST_SUB` and must be used if the port installs [.filename]#*.cmake# depending on the build type (see package:devel/kf5-kcrash[] for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting `CMAKE_BUILD_TYPE` in [.filename]#CMakeLists.txt#. To make a port for such a project respect `CFLAGS` and `WITH_DEBUG`, the `CMAKE_BUILD_TYPE` definitions must be removed from those files. Most CMake-based projects support an out-of-source method of building. The out-of-source build for a port is the default setting. An in-source build can be requested by using the `:insource` suffix. With out-of-source builds, `CONFIGURE_WRKSRC`, `BUILD_WRKSRC` and `INSTALL_WRKSRC` will be set to `${WRKDIR}/.build` and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact. [[using-cmake-example]] .`USES= cmake` Example [example] ==== This snippet demonstrates the use of CMake for a port. `CMAKE_SOURCE_PATH` is not usually required, but can be set when the sources are not located in the top directory, or if only a subset of the project is intended to be built by the port. [.programlisting] .... USES= cmake CMAKE_SOURCE_PATH= ${WRKSRC}/subproject .... ==== [[using-cmake-example2]] .`CMAKE_ON` and `CMAKE_OFF` [example] ==== When adding boolean values to `CMAKE_ARGS`, it is easier to use the `CMAKE_ON` and `CMAKE_OFF` variables instead. This: [.programlisting] .... CMAKE_ON= VAR1 VAR2 CMAKE_OFF= VAR3 .... Is equivalent to: [.programlisting] .... CMAKE_ARGS= -DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE .... [IMPORTANT] ====== This is only for the default values off `CMAKE_ARGS`. The helpers described in crossref:makefiles[options-cmake_bool,`OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`] use the same semantics, but for optional values. ====== ==== [[using-scons]] === Using `scons` If the port uses SCons, define `USES=scons`. To make third party [.filename]#SConstruct# respect everything that is passed to SCons in the environment (that is, most importantly, `CC/CXX/CFLAGS/CXXFLAGS`), patch [.filename]#SConstruct# so build `Environment` is constructed like this: [.programlisting] .... env = Environment(**ARGUMENTS) .... It may be then modified with `env.Append` and `env.Replace`. [[using-cargo]] === Building Rust Applications with `cargo` For ports that use Cargo, define `USES=cargo`. [[using-cargo-user-variables]] .Variables the Users Can Define for `cargo` Builds [cols="1,1,1", frame="none", options="header"] |=== | Variable | Default | Description |`CARGO_CRATES` | |List of crates the port depends on. Each entry needs to have a format like `cratename-semver` for example, `libc-0.2.40`. Port maintainers can generate this list from [.filename]#Cargo.lock# using `make cargo-crates`. Manually bumping crate versions is possible but be mindful of transitive dependencies. |`CARGO_FEATURES` | |List of application features to build (space separated list). To deactivate all default features add the special token `--no-default-features` to `CARGO_FEATURES`. Manually passing it to `CARGO_BUILD_ARGS`, `CARGO_INSTALL_ARGS`, and `CARGO_TEST_ARGS` is not needed. |`CARGO_CARGOTOML` |`${WRKSRC}/Cargo.toml` |The path to the [.filename]#Cargo.toml# to use. |`CARGO_CARGOLOCK` |`${WRKSRC}/Cargo.lock` |The path to the [.filename]#Cargo.lock# to use for `make cargo-crates`. It is possible to specify more than one lock file when necessary. |`CARGO_ENV` | |A list of environment variables to pass to Cargo similar to `MAKE_ENV`. |`RUSTFLAGS` | |Flags to pass to the Rust compiler. |`CARGO_CONFIGURE` |`yes` |Use the default `do-configure`. |`CARGO_UPDATE_ARGS` | |Extra arguments to pass to Cargo during the configure phase. Valid arguments can be looked up with `cargo update --help`. |`CARGO_BUILDDEP` |`yes` |Add a build dependency on package:lang/rust[]. |`CARGO_CARGO_BIN` |`${LOCALBASE}/bin/cargo` |Location of the `cargo` binary. |`CARGO_BUILD` |`yes` |Use the default `do-build`. |`CARGO_BUILD_ARGS` | |Extra arguments to pass to Cargo during the build phase. Valid arguments can be looked up with `cargo build --help`. |`CARGO_INSTALL` |`yes` |Use the default `do-install`. |`CARGO_INSTALL_ARGS` | |Extra arguments to pass to Cargo during the install phase. Valid arguments can be looked up with `cargo install --help`. |`CARGO_INSTALL_PATH` |`.` |Path to the crate to install. This is passed to `cargo install` via its `--path` argument. When multiple paths are specified `cargo install` is run multiple times. |`CARGO_TEST` |`yes` |Use the default `do-test`. |`CARGO_TEST_ARGS` | |Extra arguments to pass to Cargo during the test phase. Valid arguments can be looked up with `cargo test --help`. |`CARGO_TARGET_DIR` |`${WRKDIR}/target` |Location of the cargo output directory. |`CARGO_DIST_SUBDIR` |[.filename]#rust/crates# |Directory relative to `DISTDIR` where the crate distribution files will be stored. |`CARGO_VENDOR_DIR` |`${WRKSRC}/cargo-crates` |Location of the vendor directory where all crates will be extracted to. Try to keep this under `PATCH_WRKSRC`, so that patches can be applied easily. |`CARGO_USE_GITHUB` |`no` |Enable fetching of crates locked to specific Git commits on GitHub via `GH_TUPLE`. This will try to patch all [.filename]#Cargo.toml# under `WRKDIR` to point to the offline sources instead of fetching them from a Git repository during the build. |`CARGO_USE_GITLAB` |`no` |Same as `CARGO_USE_GITHUB` but for GitLab instances and `GL_TUPLE`. |=== [[cargo-ex1]] .Creating a Port for a Simple Rust Application [example] ==== Creating a Cargo based port is a three stage process. First we need to provide a ports template that fetches the application distribution file: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower .include .... Generate an initial [.filename]#distinfo#: [source,shell] .... % make makesum => Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s .... Now the distribution file is ready to use and we can go ahead and extract crate dependencies from the bundled [.filename]#Cargo.lock#: [source,shell] .... % make cargo-crates CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .... The output of this command needs to be pasted directly into the Makefile: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .include .... [.filename]#distinfo# needs to be regenerated to contain all the crate distribution files: [source,shell] .... % make makesum => rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s => rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s => rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s => rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s => rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/. [...] .... The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. ==== [[cargo-ex2]] .Enabling Additional Application Features [example] ==== Some applications define additional features in their [.filename]#Cargo.toml#. They can be compiled in by setting `CARGO_FEATURES` in the port. Here we enable Tokei's `json` and `yaml` features: [.programlisting] .... CARGO_FEATURES= json yaml .... ==== [[cargo-ex4]] .Encoding Application Features As Port Options [example] ==== An example `[features]` section in [.filename]#Cargo.toml# could look like this: [.programlisting] .... [features] pulseaudio_backend = ["librespot-playback/pulseaudio-backend"] portaudio_backend = ["librespot-playback/portaudio-backend"] default = ["pulseaudio_backend"] .... `pulseaudio_backend` is a default feature. It is always enabled unless we explicitly turn off default features by adding `--no-default-features` to `CARGO_FEATURES`. Here we turn the `portaudio_backend` and `pulseaudio_backend` features into port options: [.programlisting] .... CARGO_FEATURES= --no-default-features OPTIONS_DEFINE= PORTAUDIO PULSEAUDIO PORTAUDIO_VARS= CARGO_FEATURES+=portaudio_backend PULSEAUDIO_VARS= CARGO_FEATURES+=pulseaudio_backend .... ==== [[cargo-ex3]] .Listing Crate Licenses [example] ==== Crates have their own licenses. It is important to know what they are when adding a `LICENSE` block to the port (see crossref:makefiles[licenses,Licenses]). The helper target `cargo-crates-licenses` will try to list all the licenses of all crates defined in `CARGO_CRATES`. [source,shell] .... % make cargo-crates-licenses aho-corasick-0.6.4 Unlicense/MIT ansi_term-0.11.0 MIT arrayvec-0.4.7 MIT/Apache-2.0 atty-0.2.9 MIT bitflags-1.0.1 MIT/Apache-2.0 byteorder-1.2.2 Unlicense/MIT [...] .... [NOTE] ====== The license names `make cargo-crates-licenses` outputs are SPDX 2.1 licenses expression which do not match the license names defined in the ports framework. They need to be translated to the names from crossref:makefiles[licenses-license-list,Predefined License List]. ====== ==== [[using-meson]] === Using `meson` For ports that use Meson, define `USES=meson`. [[using-meson-variables]] .Variables for Ports That Use `meson` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`MESON_ARGS` |Port specific Meson flags to be passed to the `meson` binary. |`MESON_BUILD_DIR` |Path to the build directory relative to `WRKSRC`. Default is `_build`. |=== [[using-meson-example]] .`USES=meson` Example [example] ==== This snippet demonstrates the use of Meson for a port. [.programlisting] .... USES= meson MESON_ARGS= -Dfoo=enabled .... ==== [[using-go]] === Building Go Applications For ports that use Go, define `USES=go`. Refer to crossref:uses[uses-go,`go`] for a list of variables that can be set to control the build process. [[go-ex1]] .Creating a Port for a Go Modules Based Application [example] ==== In most cases, it is sufficient to set the `GO_MODULE` variable to the value specified by the `module` directive in `go.mod`: [.programlisting] .... PORTNAME= hey PORTVERSION= 0.1.4 DISTVERSIONPREFIX= v CATEGORIES= benchmarks MAINTAINER= dmgk@FreeBSD.org COMMENT= Tiny program that sends some load to a web application LICENSE= APACHE20 LICENSE_FILE= ${WRKSRC}/LICENSE USES= go:modules GO_MODULE= github.com/rakyll/hey PLIST_FILES= bin/hey .include .... If the "easy" way is not adequate or more control over dependencies is needed, the full porting process is described below. Creating a Go based port is a five stage process. First we need to provide a ports template that fetches the application distribution file: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy USES= go:modules USE_GITHUB= yes GH_ACCOUNT= motemen .include .... Generate an initial [.filename]#distinfo#: [source,shell] .... % make makesum ===> License MIT accepted by the user => motemen-ghq-v0.12.5_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz fetch: https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz: size of remote file is not known motemen-ghq-v0.12.5_GH0.tar.gz 32 kB 177 kBps 00s .... Now the distribution file is ready to use and we can extract the required Go module dependencies. This step requires having package:ports-mgmt/modules2tuple[] installed: [source,shell] .... % make gomod-vendor [...] GH_TUPLE= \ Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .... The output of this command needs to be pasted directly into the Makefile: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy USES= go:modules USE_GITHUB= yes GH_ACCOUNT= motemen GH_TUPLE= Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .include .... [.filename]#distinfo# needs to be regenerated to contain all the distribution files: [source,shell] .... % make makesum => Songmu-gitconfig-v0.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz fetch: https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz: size of remote file is not known Songmu-gitconfig-v0.0.2_GH0.tar.gz 5662 B 936 kBps 00s => daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz fetch: https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz: size of remote file is not known daviddengcn-go-colortext-186a3d44e920_GH0.tar. 4534 B 1098 kBps 00s [...] .... The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. ==== [[go-ex2]] .Setting Output Binary Name or Installation Path [example] ==== Some ports need to install the resulting binary under a different name or to a path other than the default `${PREFIX}/bin`. This can be done by using `GO_TARGET` tuple syntax, for example: [.programlisting] .... GO_TARGET= ./cmd/ipfs:ipfs-go .... will install `ipfs` binary as `${PREFIX}/bin/ipfs-go` and [.programlisting] .... GO_TARGET= ./dnscrypt-proxy:${PREFIX}/sbin/dnscrypt-proxy .... will install `dnscrypt-proxy` to `${PREFIX}/sbin`. ==== [[using-cabal]] === Building Haskell Applications with `cabal` For ports that use Cabal, build system defines `USES=cabal`. Refer to crossref:uses[uses-cabal,`cabal`] for a list of variables that can be set to control the build process. [[cabal-ex1]] .Creating a Port for a Hackage-hosted Haskell Application [example] ==== When preparing a Haskell Cabal port, the package:devel/hs-cabal-install[] program is required, so make sure it is installed beforehand. First we need to define common ports variables that allows cabal-install to fetch the package distribution file: [.programlisting] .... PORTNAME= ShellCheck DISTVERSION= 0.6.0 CATEGORIES= devel MAINTAINER= haskell@FreeBSD.org COMMENT= Shell script analysis tool USES= cabal .include .... This minimal Makefile allows us to fetch the distribution file: [source,shell] .... % make cabal-extract [...] Downloading the latest package list from hackage.haskell.org cabal get ShellCheck-0.6.0 Downloading ShellCheck-0.6.0 Downloaded ShellCheck-0.6.0 Unpacking to ShellCheck-0.6.0/ .... Now we have ShellCheck.cabal package description file, which allows us to fetch all package's dependencies, including transitive ones: [source,shell] .... % make cabal-extract-deps [...] Resolving dependencies... Downloading base-orphans-0.8.2 Downloaded base-orphans-0.8.2 Downloading primitive-0.7.0.0 Starting base-orphans-0.8.2 (lib) Building base-orphans-0.8.2 (lib) Downloaded primitive-0.7.0.0 Downloading dlist-0.8.0.7 [...] .... As a side effect, the package's dependencies are also compiled, so the command may take some time. Once done, a list of required dependencies can generated: [source,shell] .... % make make-use-cabal USE_CABAL=QuickCheck-2.12.6.1 \ hashable-1.3.0.0 \ integer-logarithms-1.0.3 \ [...] .... Haskell packages may contain revisions, just like FreeBSD ports. Revisions can affect only [.filename]#.cabal# files, but it is still important to pull them in. To check `USE_CABAL` items for available revision updates, run following command: [source,shell] .... % make make-use-cabal-revs USE_CABAL=QuickCheck-2.12.6.1_1 \ hashable-1.3.0.0 \ integer-logarithms-1.0.3_2 \ [...] .... Note additional version numbers after `_` symbol. Put newly generated `USE_CABAL` list instead of an old one. Finally, [.filename]#distinfo# needs to be regenerated to contain all the distribution files: [source,shell] .... % make makesum => ShellCheck-0.6.0.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/ShellCheck-0.6.0/ShellCheck-0.6.0.tar.gz ShellCheck-0.6.0.tar.gz 136 kB 642 kBps 00s => QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 65 kB 361 kBps 00s [...] .... The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. ==== [[using-autotools]] == Using GNU Autotools If a port needs any of the GNU Autotools software, add `USES=autoreconf`. See crossref:uses[uses-autoreconf,`autoreconf`] for more information. [[using-gettext]] == Using GNU `gettext` [[using-gettext-basic]] === Basic Usage If the port requires `gettext`, set `USES= gettext`, and the port will inherit a dependency on [.filename]#libintl.so# from package:devel/gettext[]. Other values for `gettext` usage are listed in crossref:uses[uses-gettext,`USES=gettext`]. A rather common case is a port using `gettext` and `configure`. Generally, GNU `configure` should be able to locate `gettext` automatically. [.programlisting] .... USES= gettext GNU_CONFIGURE= yes .... If it ever fails to, hints at the location of `gettext` can be passed in `CPPFLAGS` and `LDFLAGS` using `localbase` as follows: [.programlisting] .... USES= gettext localbase:ldflags GNU_CONFIGURE= yes .... [[using-gettext-optional]] === Optional Usage Some software products allow for disabling NLS. For example, through passing `--disable-nls` to `configure`. In that case, the port must use `gettext` conditionally, depending on the status of the `NLS` option. For ports of low to medium complexity, use this idiom: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS OPTIONS_SUB= yes NLS_USES= gettext NLS_CONFIGURE_ENABLE= nls .include .... Or using the older way of using options: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS .include .if ${PORT_OPTIONS:MNLS} USES+= gettext PLIST_SUB+= NLS="" .else CONFIGURE_ARGS+= --disable-nls PLIST_SUB+= NLS="@comment " .endif .include .... The next item on the to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The [.filename]#Makefile# part of this task is already provided by the idiom. It is explained in the section on crossref:plist[plist-sub,advanced [.filename]#pkg-plist# practices]. In a nutshell, each occurrence of `%%NLS%%` in [.filename]#pkg-plist# will be replaced by "`@comment `" if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by `%%NLS%%` will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. Then insert `%%NLS%%` before each path to a message catalog file in [.filename]#pkg-plist#. For example: [.programlisting] .... %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo .... In high complexity cases, more advanced techniques may be needed, such as crossref:plist[plist-dynamic,dynamic packing list generation]. [[using-gettext-catalog-directories]] === Handling Message Catalog Directories There is a point to note about installing message catalog files. The target directories for them, which reside under [.filename]#LOCALBASE/share/locale#, must not be created and removed by a port. The most popular languages have their respective directories listed in [.filename]#PORTSDIR/Templates/BSD.local.dist#. The directories for many other languages are governed by the package:devel/gettext[] port. Consult its [.filename]#pkg-plist# and see whether the port is going to install a message catalog file for a unique language. [[using-perl]] == Using Perl If `MASTER_SITES` is set to `CPAN`, the correct subdirectory is usually selected automatically. If the default subdirectory is wrong, `CPAN/Module` can be used to change it. `MASTER_SITES` can also be set to the old `MASTER_SITE_PERL_CPAN`, then the preferred value of `MASTER_SITE_SUBDIR` is the top-level hierarchy name. For example, the recommended value for `p5-Module-Name` is `Module`. The top-level hierarchy can be examined at http://cpan.org/modules/by-module/[cpan.org]. This keeps the port working when the author of the module changes. The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as `MASTER_SITE_SUBDIR` is allowed. The `CPAN:AUTHOR` macro can be used, which will be translated to the hashed author directory. For example, `CPAN:AUTHOR` will be converted to `authors/id/A/AU/AUTHOR`. When a port needs Perl support, it must set `USES=perl5` with the optional `USE_PERL5` described in crossref:uses[uses-perl5,the perl5 USES description]. [[using-perl-variables]] .Read-Only Variables for Ports That Use Perl [cols="1,1", frame="none", options="header"] |=== | Read only variables | Means |`PERL` |The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace "``#!``"lines in scripts, use crossref:uses[uses-shebangfix,`shebangfix`]. |`PERL_VERSION` |The full version of Perl installed (for example, `5.8.9`). |`PERL_LEVEL` |The installed Perl version as an integer of the form `MNNNPP` (for example, `500809`). |`PERL_ARCH` |Where Perl stores architecture dependent libraries. Defaults to `${ARCH}-freebsd`. |`PERL_PORT` |Name of the Perl port that is installed (for example, `perl5`). |`SITE_PERL` |Directory name where site specific Perl packages go. This value is added to `PLIST_SUB`. |=== [NOTE] ==== Ports of Perl modules which do not have an official website must link to `cpan.org` in the WWW line of [.filename]#pkg-descr#. The preferred URL form is `http://search.cpan.org/dist/Module-Name/` (including the trailing slash). ==== [NOTE] ==== Do not use `${SITE_PERL}` in dependency declarations. Doing so assumes that [.filename]#perl5.mk# has been included, which is not always true. Ports depending on this port will have incorrect dependencies if this port's files move later in an upgrade. The right way to declare Perl module dependencies is shown in the example below. ==== [[use-perl-dependency-example]] .Perl Dependency Example [example] ==== [.programlisting] .... p5-IO-Tee>=0.64:devel/p5-IO-Tee .... ==== For Perl ports that install manual pages, the macro `PERL5_MAN3` and `PERL5_MAN1` can be used inside [.filename]#pkg-plist#. For example, [.programlisting] .... lib/perl5/5.14/man/man1/event.1.gz lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz .... can be replaced with [.programlisting] .... %%PERL5_MAN1%%/event.1.gz %%PERL5_MAN3%%/AnyEvent::I3.3.gz .... [NOTE] ==== There are no `PERL5_MAN_x_` macros for the other sections (_x_ in `2` and `4` to `9`) because those get installed in the regular directories. ==== [[use-perl-ex-build]] .A Port Which Only Requires Perl to Build [example] ==== As the default USE_PERL5 value is build and run, set it to: [.programlisting] .... USES= perl5 USE_PERL5= build .... ==== [[use-perl-ex-patch]] .A Port Which Also Requires Perl to Patch [example] ==== From time to time, using man:sed[1] for patching is not enough. When using man:perl[1] is easier, use: [.programlisting] .... USES= perl5 USE_PERL5= patch build run .... ==== [[use-perl-ex-configure]] .A Perl Module Which Needs `ExtUtils::MakeMaker` to Build [example] ==== Most Perl modules come with a [.filename]#Makefile.PL# configure script. In this case, set: [.programlisting] .... USES= perl5 USE_PERL5= configure .... ==== [[use-perl-ex-modbuild]] .A Perl Module Which Needs `Module::Build` to Build [example] ==== When a Perl module comes with a [.filename]#Build.PL# configure script, it can require Module::Build, in which case, set [.programlisting] .... USES= perl5 USE_PERL5= modbuild .... If it instead requires Module::Build::Tiny, set [.programlisting] .... USES= perl5 USE_PERL5= modbuildtiny .... ==== [[using-x11]] == Using X11 [[x11-variables]] === X.Org Components The X11 implementation available in The Ports Collection is X.Org. If the application depends on X components, add `USES= xorg` and set `USE_XORG` to the list of required components. A full list can be found in crossref:uses[uses-xorg,`xorg`]. The Mesa Project is an effort to provide free OpenGL implementation. To specify a dependency on various components of this project, use `USES= gl` and `USE_GL`. See crossref:uses[uses-gl,`gl`] for a full list of available components. For backwards compatibility, the value of `yes` maps to `glu`. [[use-xorg-example]] .`USE_XORG` Example [example] ==== [.programlisting] .... USES= gl xorg USE_GL= glu USE_XORG= xrender xft xkbfile xt xaw .... ==== [[using-xorg-variables]] .Variables for Ports That Use X [cols="1,1", frame="none"] |=== |`USES= imake` |The port uses `imake`. |`XMKMF` |Set to the path of `xmkmf` if not in the `PATH`. Defaults to `xmkmf -a`. |=== [[using-x11-vars]] .Using X11-Related Variables [example] ==== [.programlisting] .... # Use some X11 libraries USES= xorg USE_XORG= x11 xpm .... ==== [[x11-motif]] === Ports That Require Motif If the port requires a Motif library, define `USES= motif` in the [.filename]#Makefile#. Default Motif implementation is package:x11-toolkits/open-motif[]. Users can choose package:x11-toolkits/lesstif[] instead by setting `WANT_LESSTIF` in their [.filename]#make.conf#. `MOTIFLIB` will be set by [.filename]#motif.mk# to reference the appropriate Motif library. Please patch the source of the port to use `${MOTIFLIB}` wherever the Motif library is referenced in the original [.filename]#Makefile# or [.filename]#Imakefile#. There are two common cases: * If the port refers to the Motif library as `-lXm` in its [.filename]#Makefile# or [.filename]#Imakefile#, substitute `${MOTIFLIB}` for it. * If the port uses `XmClientLibs` in its [.filename]#Imakefile#, change it to `${MOTIFLIB} ${XTOOLLIB} ${XLIB}`. Note that `MOTIFLIB` (usually) expands to `-L/usr/local/lib -lXm -lXp` or `/usr/local/lib/libXm.a`, so there is no need to add `-L` or `-l` in front. [[x11-fonts]] === X11 Fonts If the port installs fonts for the X Window System, put them in [.filename]#LOCALBASE/lib/X11/fonts/local#. [[x11-fake-display]] === Getting a Fake `DISPLAY` with Xvfb Some applications require a working X11 display for compilation to succeed. This poses a problem for machines that operate headless. When this variable is used, the build infrastructure will start the virtual framebuffer X server. The working `DISPLAY` is then passed to the build. See crossref:uses[uses-display,`USES=display`] for the possible arguments. [.programlisting] .... USES= display .... [[desktop-entries]] === Desktop Entries Desktop entries (http://standards.freedesktop.org/desktop-entry-spec/latest/[a Freedesktop standard]) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in the application menus of compatible desktop environments. Desktop entries originated in the GNOME desktop environment, but are now a standard and also work with KDE and Xfce. This bit of automation provides a real benefit to the user, and desktop entries are encouraged for applications which can be used in a desktop environment. [[desktop-entries-predefined]] ==== Using Predefined [.filename]#.desktop# Files Ports that include predefined [.filename]#*.desktop# must include those files in [.filename]#pkg-plist# and install them in the [.filename]#$LOCALBASE/share/applications# directory. The crossref:makefiles[install-macros,`INSTALL_DATA` macro] is useful for installing these files. [[updating-desktop-database]] ==== Updating Desktop Database If a port has a MimeType entry in its [.filename]#portname.desktop#, the desktop database must be updated after install and deinstall. To do this, define `USES`= desktop-file-utils. [[desktop-entries-macro]] ==== Creating Desktop Entries with `DESKTOP_ENTRIES` Desktop entries can be easily created for applications by using `DESKTOP_ENTRIES`. A file named [.filename]#name.desktop# will be created, installed, and added to [.filename]#pkg-plist# automatically. Syntax is: [.programlisting] .... DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify .... The list of possible categories is available on the http://standards.freedesktop.org/menu-spec/latest/apa.html[Freedesktop website]. `StartupNotify` indicates whether the application is compatible with _startup notifications_. These are typically a graphic indicator like a clock that appear at the mouse pointer, menu, or panel to give the user an indication when a program is starting. A program that is compatible with startup notifications clears the indicator after it has started. Programs that are not compatible with startup notifications would never clear the indicator (potentially confusing and infuriating the user), and must have `StartupNotify` set to `false` so the indicator is not shown at all. Example: [.programlisting] .... DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ "${DATADIR}/xtra/graf/tome-128.png" \ "tome -v -g" "Application;Game;RolePlaying;" \ false .... [[using-gnome]] == Using GNOME [[using-gnome-introduction]] === Introduction This chapter explains the GNOME framework as used by ports. The framework can be loosely divided into the base components, GNOME desktop components, and a few special macros that simplify the work of port maintainers. [[use-gnome]] === Using `USE_GNOME` Adding this variable to the port allows the use of the macros and components defined in [.filename]#bsd.gnome.mk#. The code in [.filename]#bsd.gnome.mk# adds the needed build-time, run-time or library dependencies or the handling of special files. GNOME applications under FreeBSD use the `USE_GNOME` infrastructure. Include all the needed components as a space-separated list. The `USE_GNOME` components are divided into these virtual lists: basic components, GNOME 3 components and legacy components. If the port needs only GTK3 libraries, this is the shortest way to define it: [.programlisting] .... USE_GNOME= gtk30 .... `USE_GNOME` components automatically add the dependencies they need. Please see <> for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies. Here is an example [.filename]#Makefile# for a GNOME port that uses many of the techniques outlined in this document. Please use it as a guide for creating new ports. [.programlisting] .... # $FreeBSD$ PORTNAME= regexxer DISTVERSION= 0.10 CATEGORIES= devel textproc gnome MASTER_SITES= GNOME MAINTAINER= kwm@FreeBSD.org COMMENT= Interactive tool for performing search and replace operations USES= gettext gmake localbase:ldflags pathfix pkgconfig tar:xz GNU_CONFIGURE= yes USE_GNOME= gnomeprefix intlhack gtksourceviewmm3 GLIB_SCHEMAS= org.regexxer.gschema.xml .include .... [NOTE] ==== The `USE_GNOME` macro without any arguments does not add any dependencies to the port. `USE_GNOME` cannot be set after [.filename]#bsd.port.pre.mk#. ==== [[using-gnome-variables]] === Variables This section explains which macros are available and how they are used. Like they are used in the above example. The <> has a more in-depth explanation. `USE_GNOME` has to be set for these macros to be of use. `GLIB_SCHEMAS`:: List of all the glib schema files the port installs. The macro will add the files to the port plist and handle the registration of these files on install and deinstall. + The glib schema files are written in XML and end with the [.filename]#gschema.xml# extension. They are installed in the [.filename]#share/glib-2.0/schemas/# directory. These schema files contain all application config values with their default settings. The actual database used by the applications is built by glib-compile-schema, which is run by the `GLIB_SCHEMAS` macro. + [.programlisting] .... GLIB_SCHEMAS=foo.gschema.xml .... + [NOTE] ==== Do not add glib schemas to the [.filename]#pkg-plist#. If they are listed in [.filename]#pkg-plist#, they will not be registered and the applications might not work properly. ==== `GCONF_SCHEMAS`:: List all the gconf schema files. The macro will add the schema files to the port plist and will handle their registration on install and deinstall. + GConf is the XML-based database that virtually all GNOME applications use for storing their settings. These files are installed into the [.filename]#etc/gconf/schemas# directory. This database is defined by installed schema files that are used to generate [.filename]#%gconf.xml# key files. For each schema file installed by the port, there must be an entry in the [.filename]#Makefile#: + [.programlisting] .... GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas .... + [NOTE] ==== Gconf schemas are listed in the `GCONF_SCHEMAS` macro rather than [.filename]#pkg-plist#. If they are listed in [.filename]#pkg-plist#, they will not be registered and the applications might not work properly. ==== `INSTALLS_OMF`:: Open Source Metadata Framework (OMF) files are commonly used by GNOME 2 applications. These files contain the application help file information, and require special processing by ScrollKeeper/rarian. To properly register OMF files when installing GNOME applications from packages, make sure that `omf` files are listed in `pkg-plist` and that the port [.filename]#Makefile# has `INSTALLS_OMF` defined: + [.programlisting] .... INSTALLS_OMF=yes .... + When set, [.filename]#bsd.gnome.mk# automatically scans [.filename]#pkg-plist# and adds appropriate `@exec` and `@unexec` directives for each [.filename]#.omf# to track in the OMF registration database. [[gnome-components]] == GNOME Components For further help with a GNOME port, look at some of the link:https://www.FreeBSD.org/ports/gnome.html[existing ports] for examples. The link:https://www.FreeBSD.org/gnome/[FreeBSD GNOME page] has contact information if more help is needed. The components are divided into GNOME components that are currently in use and legacy components. If the component supports argument, they are listed between parenthesis in the description. The first is the default. "Both" is shown if the component defaults to adding to both build and run dependencies. [[gnome-components-list]] .GNOME Components [cols="1,1,1", options="header"] |=== | Component | Associated program | Description |`atk` |accessibility/atk |Accessibility toolkit (ATK) |`atkmm` |accessibility/atkmm |c++ bindings for atk |`cairo` |graphics/cairo |Vector graphics library with cross-device output support |`cairomm` |graphics/cairomm |c++ bindings for cairo |`dconf` |devel/dconf |Configuration database system (both, build, run) |`evolutiondataserver3` |databases/evolution-data-server |Data backends for the Evolution integrated mail/PIM suite |`gdkpixbuf2` |graphics/gdk-pixbuf2 |Graphics library for GTK+ |`glib20` |devel/glib20 |GNOME core library `glib20` |`glibmm` |devel/glibmm |c++ bindings for glib20 |`gnomecontrolcenter3` |sysutils/gnome-control-center |GNOME 3 Control Center |`gnomedesktop3` |x11/gnome-desktop |GNOME 3 desktop UI library |`gsound` |audio/gsound |GObject library for playing system sounds (both, build, run) |`gtk-update-icon-cache` |graphics/gtk-update-icon-cache |Gtk-update-icon-cache utility from the Gtk+ toolkit |`gtk20` |x11-toolkits/gtk20 |Gtk+ 2 toolkit |`gtk30` |x11-toolkits/gtk30 |Gtk+ 3 toolkit |`gtkmm20` |x11-toolkits/gtkmm20 |c++ bindings 2.0 for the gtk20 toolkit |`gtkmm24` |x11-toolkits/gtkmm24 |c++ bindings 2.4 for the gtk20 toolkit |`gtkmm30` |x11-toolkits/gtkmm30 |c++ bindings 3.0 for the gtk30 toolkit |`gtksourceview2` |x11-toolkits/gtksourceview2 |Widget that adds syntax highlighting to GtkTextView |`gtksourceview3` |x11-toolkits/gtksourceview3 |Text widget that adds syntax highlighting to the GtkTextView widget |`gtksourceviewmm3` |x11-toolkits/gtksourceviewmm3 |c++ bindings for the gtksourceview3 library |`gvfs` |devel/gvfs |GNOME virtual file system |`intltool` |textproc/intltool |Tool for internationalization (also see intlhack) |`introspection` |devel/gobject-introspection |Basic introspection bindings and tools to generate introspection bindings. Most of the time :build is enough, :both/:run is only need for applications that use introspection bindings. (both, build, run) |`libgda5` |databases/libgda5 |Provides uniform access to different kinds of data sources |`libgda5-ui` |databases/libgda5-ui |UI library from the libgda5 library |`libgdamm5` |databases/libgdamm5 |c++ bindings for the libgda5 library |`libgsf` |devel/libgsf |Extensible I/O abstraction for dealing with structured file formats |`librsvg2` |graphics/librsvg2 |Library for parsing and rendering SVG vector-graphic files |`libsigc++20` |devel/libsigc++20 |Callback Framework for C++ |`libxml++26` |textproc/libxml++26 |c++ bindings for the libxml2 library |`libxml2` |textproc/libxml2 |XML parser library (both, build, run) |`libxslt` |textproc/libxslt |XSLT C library (both, build, run) |`metacity` |x11-wm/metacity |Window manager from GNOME |`nautilus3` |x11-fm/nautilus |GNOME file manager |`pango` |x11-toolkits/pango |Open-source framework for the layout and rendering of i18n text |`pangomm` |x11-toolkits/pangomm |c++ bindings for the pango library |`py3gobject3` |devel/py3-gobject3 |Python 3, GObject 3.0 bindings |`pygobject3` |devel/py-gobject3 |Python 2, GObject 3.0 bindings |`vte3` |x11-toolkits/vte3 |Terminal widget with improved accessibility and I18N support |=== [[gnome-components-macro]] .GNOME Macro Components [cols="1,1", options="header"] |=== | Component | Description |`gnomeprefix` |Supply `configure` with some default locations. |`intlhack` |Same as intltool, but patches to make sure [.filename]#share/locale/# is used. Please only use when `intltool` alone is not enough. |`referencehack` |This macro is there to help splitting of the API or reference documentation into its own port. |=== [[gnome-components-legacy]] .GNOME Legacy Components [cols="1,1,1", options="header"] |=== | Component | Associated program | Description |`atspi` |accessibility/at-spi |Assistive Technology Service Provider Interface |`esound` |audio/esound |Enlightenment sound package |`gal2` |x11-toolkits/gal2 |Collection of widgets taken from GNOME 2 gnumeric |`gconf2` |devel/gconf2 |Configuration database system for GNOME 2 |`gconfmm26` |devel/gconfmm26 |c++ bindings for gconf2 |`gdkpixbuf` |graphics/gdk-pixbuf |Graphics library for GTK+ |`glib12` |devel/glib12 |glib 1.2 core library |`gnomedocutils` |textproc/gnome-doc-utils |GNOME doc utils |`gnomemimedata` |misc/gnome-mime-data |MIME and Application database for GNOME 2 |`gnomesharp20` |x11-toolkits/gnome-sharp20 |GNOME 2 interfaces for the .NET runtime |`gnomespeech` |accessibility/gnome-speech |GNOME 2 text-to-speech API |`gnomevfs2` |devel/gnome-vfs |GNOME 2 Virtual File System |`gtk12` |x11-toolkits/gtk12 |Gtk+ 1.2 toolkit |`gtkhtml3` |www/gtkhtml3 |Lightweight HTML rendering/printing/editing engine |`gtkhtml4` |www/gtkhtml4 |Lightweight HTML rendering/printing/editing engine |`gtksharp20` |x11-toolkits/gtk-sharp20 |GTK+ and GNOME 2 interfaces for the .NET runtime |`gtksourceview` |x11-toolkits/gtksourceview |Widget that adds syntax highlighting to GtkTextView |`libartgpl2` |graphics/libart_lgpl |Library for high-performance 2D graphics |`libbonobo` |devel/libbonobo |Component and compound document system for GNOME 2 |`libbonoboui` |x11-toolkits/libbonoboui |GUI frontend to the libbonobo component of GNOME 2 |`libgda4` |databases/libgda4 |Provides uniform access to different kinds of data sources |`libglade2` |devel/libglade2 |GNOME 2 glade library |`libgnome` |x11/libgnome |Libraries for GNOME 2, a GNU desktop environment |`libgnomecanvas` |graphics/libgnomecanvas |Graphics library for GNOME 2 |`libgnomekbd` |x11/libgnomekbd |GNOME 2 keyboard shared library |`libgnomeprint` |print/libgnomeprint |Gnome 2 print support library |`libgnomeprintui` |x11-toolkits/libgnomeprintui |Gnome 2 print support library |`libgnomeui` |x11-toolkits/libgnomeui |Libraries for the GNOME 2 GUI, a GNU desktop environment |`libgtkhtml` |www/libgtkhtml |Lightweight HTML rendering/printing/editing engine |`libgtksourceviewmm` |x11-toolkits/libgtksourceviewmm |c++ binding of GtkSourceView |`libidl` |devel/libIDL |Library for creating trees of CORBA IDL file |`libsigc++12` |devel/libsigc++12 |Callback Framework for C++ |`libwnck` |x11-toolkits/libwnck |Library used for writing pagers and taskslists |`libwnck3` |x11-toolkits/libwnck3 |Library used for writing pagers and taskslists |`orbit2` |devel/ORBit2 |High-performance CORBA ORB with support for the C language |`pygnome2` |x11-toolkits/py-gnome2 |Python bindings for GNOME 2 |`pygobject` |devel/py-gobject |Python 2, GObject 2.0 bindings |`pygtk2` |x11-toolkits/py-gtk2 |Set of Python bindings for GTK+ |`pygtksourceview` |x11-toolkits/py-gtksourceview |Python bindings for GtkSourceView 2 |`vte` |x11-toolkits/vte |Terminal widget with improved accessibility and I18N support |=== [[gnome-components-deprecated]] .Deprecated Components: Do Not Use [cols="1,1", options="header"] |=== | Component | Description |`pangox-compat` |pangox-compat has been deprecated and split off from the pango package. |=== [[using-qt]] == Using Qt [NOTE] ==== For ports that are part of Qt itself, see crossref:uses[uses-qt-dist,`qt-dist`]. ==== [[qt-common]] === Ports That Require Qt The Ports Collection provides support for Qt 5 with `USES+=qt:5`. Set `USE_QT` to the list of required Qt components (libraries, tools, plugins). The Qt framework exports a number of variables which can be used by ports, some of them listed below: [[using-qt-variables]] .Variables Provided to Ports That Use Qt [cols="1,1", frame="none"] |=== |`QMAKE` |Full path to `qmake` binary. |`LRELEASE` |Full path to `lrelease` utility. |`MOC` |Full path to `moc`. |`RCC` |Full path to `rcc`. |`UIC` |Full path to `uic`. |`QT_INCDIR` |Qt include directory. |`QT_LIBDIR` |Qt libraries path. |`QT_PLUGINDIR` |Qt plugins path. |=== [[qt-components]] === Component Selection Individual Qt tool and library dependencies must be specified in `USE_QT`. Every component can be suffixed with `_build` or `_run`, the suffix indicating whether the dependency on the component is at buildtime or runtime. If unsuffixed, the component will be depended on at both build- and runtime. Usually, library components are specified unsuffixed, tool components are mostly specified with the `_build` suffix and plugin components are specified with the `_run` suffix. The most commonly used components are listed below (all available components are listed in `_USE_QT_ALL`, and `_USE_QT5_ONLY` in [.filename]#/usr/ports/Mk/Uses/qt.mk#): [[using-qt-library-list]] .Available Qt Library Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`3d` |Qt3D module |`assistant` |Qt 5 documentation browser |`canvas3d` |Qt canvas3d module |`charts` |Qt 5 charts module |`concurrent` |Qt multi-threading module |`connectivity` |Qt connectivity (Bluetooth/NFC) module |`core` |Qt core non-graphical module |`datavis3d` |Qt 5 3D data visualization module |`dbus` |Qt D-Bus inter-process communication module |`declarative` |Qt declarative framework for dynamic user interfaces |`designer` |Qt 5 graphical user interface designer |`diag` |Tool for reporting diagnostic information about Qt and its environment |`doc` |Qt 5 documentation |`examples` |Qt 5 examples sourcecode |`gamepad` |Qt 5 Gamepad Module |`graphicaleffects` |Qt Quick graphical effects |`gui` |Qt graphical user interface module |`help` |Qt online help integration module |`l10n` |Qt localized messages |`linguist` |Qt 5 translation tool |`location` |Qt location module |`multimedia` |Qt audio, video, radio and camera support module |`network` |Qt network module |`networkauth` |Qt network auth module |`opengl` |Qt 5-compatible OpenGL support module |`paths` |Command line client to QStandardPaths |`phonon4` |KDE multimedia framework |`pixeltool` |Qt 5 screen magnifier |`plugininfo` |Qt5 plugin metadata dumper |`printsupport` |Qt print support module |`qdbus` |Qt command-line interface to D-Bus |`qdbusviewer` |Qt 5 graphical interface to D-Bus |`qdoc` |Qt documentation generator |`qdoc-data` |QDoc configuration files |`qev` |Qt QWidget events introspection tool |`qmake` |Qt Makefile generator |`quickcontrols` |Set of controls for building complete interfaces in Qt Quick |`quickcontrols2` |Set of controls for building complete interfaces in Qt Quick |`remoteobjects` |Qt5 SXCML module |`script` |Qt 4-compatible scripting module |`scripttools` |Qt Script additional components |`scxml` |Qt5 SXCML module |`sensors` |Qt sensors module |`serialbus` |Qt functions to access industrial bus systems |`serialport` |Qt functions to access serial ports |`speech` |Accessibilty features for Qt5 |`sql` |Qt SQL database integration module |`sql-ibase` |Qt InterBase/Firebird database plugin |`sql-mysql` |Qt MySQL database plugin |`sql-odbc` |Qt Open Database Connectivity plugin |`sql-pgsql` |Qt PostgreSQL database plugin |`sql-sqlite2` |Qt SQLite 2 database plugin |`sql-sqlite3` |Qt SQLite 3 database plugin |`sql-tds` |Qt TDS Database Connectivity database plugin |`svg` |Qt SVG support module |`testlib` |Qt unit testing module |`uiplugin` |Custom Qt widget plugin interface for Qt Designer |`uitools` |Qt Designer UI forms support module |`virtualkeyboard` |Qt 5 Virtual Keyboard Module |`wayland` |Qt5 wrapper for Wayland |`webchannel` |Qt 5 library for integration of C++/QML with HTML/js clients |`webengine` |Qt 5 library to render web content |`webkit` |QtWebKit with a more modern WebKit code base |`websockets` |Qt implementation of WebSocket protocol |`websockets-qml` |Qt implementation of WebSocket protocol (QML bindings) |`webview` |Qt component for displaying web content |`widgets` |Qt C++ widgets module |`x11extras` |Qt platform-specific features for X11-based systems |`xml` |Qt SAX and DOM implementations |`xmlpatterns` |Qt support for XPath, XQuery, XSLT and XML Schema |=== To determine the libraries an application depends on, run `ldd` on the main executable after a successful compilation. [[using-qt-tools-list]] .Available Qt Tool Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`buildtools` |build tools (`moc`, `rcc`), needed for almost every Qt application. |`linguisttools` |localization tools: `lrelease`, `lupdate` |`qmake` |Makefile generator/build utility |=== [[using-qt-plugins-list]] .Available Qt Plugin Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`imageformats` |plugins for TGA, TIFF, and MNG image formats |=== [[qt5-components-example]] .Selecting Qt 5 Components [example] ==== In this example, the ported application uses the Qt 5 graphical user interface library, the Qt 5 core library, all of the Qt 5 code generation tools and Qt 5's Makefile generator. Since the `gui` library implies a dependency on the core library, `core` does not need to be specified. The Qt 5 code generation tools `moc`, `uic` and `rcc`, as well as the Makefile generator `qmake` are only needed at buildtime, thus they are specified with the `_build` suffix: [.programlisting] .... USES= qt:5 USE_QT= gui buildtools_build qmake_build .... ==== [[using-qmake]] === Using `qmake` If the application provides a qmake project file ([.filename]#*.pro#), define `USES= qmake` along with `USE_QT`. `USES= qmake` already implies a build dependency on qmake, therefore the qmake component can be omitted from `USE_QT`. Similar to <>, qmake supports out-of-source builds, which can be enabled by specifying the `outsource` argument (see <>). Also see <>. [[using-qmake-arguments]] .Possible Arguments for `USES= qmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`no_configure` |Do not add the configure target. This is implied by `HAS_CONFIGURE=yes` and `GNU_CONFIGURE=yes`. It is required when the build only needs the environment setup from `USES= qmake`, but otherwise runs `qmake` on its own. |`no_env` |Suppress modification of the configure and make environments. It is only required when `qmake` is used to configure the software and the build fails to understand the environment setup by `USES= qmake`. |`norecursive` |Do not pass the `-recursive` argument to `qmake`. |`outsource` |Perform an out-of-source build. |=== [[using-qmake-variables]] .Variables for Ports That Use `qmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`QMAKE_ARGS` |Port specific qmake flags to be passed to the `qmake` binary. |`QMAKE_ENV` |Environment variables to be set for the `qmake` binary. The default is `${CONFIGURE_ENV}`. |`QMAKE_SOURCE_PATH` |Path to qmake project files ([.filename]#.pro#). The default is `${WRKSRC}` if an out-of-source build is requested, empty otherwise. |=== When using `USES= qmake`, these settings are deployed: [.programlisting] .... CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ --with-qt-libraries=${QT_LIBDIR} \ --with-extra-libs=${LOCALBASE}/lib \ --with-extra-includes=${LOCALBASE}/include CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \ QMAKESPEC="${QMAKESPEC}" PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ QT_LIBDIR=${QT_LIBDIR_REL} \ QT_PLUGINDIR=${QT_PLUGINDIR_REL} .... Some configure scripts do not support the arguments above. To suppress modification of `CONFIGURE_ENV` and `CONFIGURE_ARGS`, set `USES= qmake:no_env`. [[using-qmake-example]] .`USES= qmake` Example [example] ==== This snippet demonstrates the use of qmake for a Qt 5 port: [.programlisting] .... USES= qmake:outsource qt:5 USE_QT= buildtools_build .... ==== Qt applications are often written to be cross-platform and often X11/Unix is not the platform they are developed on, which in turn leads to certain loose ends, like: * _Missing additional include paths._ Many applications come with system tray icon support, but neglect to look for includes and/or libraries in the X11 directories. To add directories to `qmake`'s include and library search paths via the command line, use: + [.programlisting] .... QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib .... * _Bogus installation paths._ Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. package:editors/texmaker[] is an example for this - look at [.filename]#patch-texmaker.pro# in the [.filename]#files# directory of that port for a template on how to remedy this directly in the `qmake` project file. [[using-kde]] == Using KDE [[kde5-variables]] === KDE Variable Definitions If the application depends on KDE, set `USES+=kde:5` and `USE_KDE` to the list of required components. `_build` and `_run` suffixes can be used to force components dependency type (for example, `baseapps_run`). If no suffix is set, a default dependency type will be used. To force both types, add the component twice with both suffixes (for example, `ecm_build ecm_run`). Available components are listed below (up-to-date components are also listed in [.filename]#/usr/ports/Mk/Uses/kde.mk#): [[using-kde-components]] .Available KDE Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`activities` |KF5 runtime and library to organize work in separate activities |`activities-stats` |KF5 statistics for activities |`activitymanagerd` |System service to manage user's activities, track the usage patterns |`akonadi` |Storage server for KDE-Pim |`akonadicalendar` |Akonadi Calendar Integration |`akonadiconsole` |Akonadi management and debugging console |`akonadicontacts` |Libraries and daemons to implement Contact Management in Akonadi |`akonadiimportwizard` |Import data from other mail clients to KMail |`akonadimime` |Libraries and daemons to implement basic email handling |`akonadinotes` |KDE library for accessing mail storages in MBox format |`akonadisearch` |Libraries and daemons to implement searching in Akonadi |`akregator` |A Feed Reader by KDE |`alarmcalendar` |KDE API for KAlarm alarms |`apidox` |KF5 API Documentation Tools |`archive` |KF5 library that provides classes for handling archive formats |`attica` |Open Collaboration Services API library KDE5 version |`attica5` |Open Collaboration Services API library KDE5 version |`auth` |KF5 abstraction to system policy and authentication features |`baloo` |KF5 Framework for searching and managing user metadata |`baloo-widgets` |BalooWidgets library |`baloo5` |KF5 Framework for searching and managing user metadata |`blog` |KDE API for weblogging access |`bookmarks` |KF5 library for bookmarks and the XBEL format |`breeze` |Plasma5 artwork, styles and assets for the Breeze visual style |`breeze-gtk` |Plasma5 Breeze visual style for Gtk |`breeze-icons` |Breeze icon theme for KDE |`calendarcore` |KDE calendar access library |`calendarsupport` |Calendar support libraries for KDEPim |`calendarutils` |KDE utility and user interface functions for accessing calendar |`codecs` |KF5 library for string manipulation |`completion` |KF5 text completion helpers and widgets |`config` |KF5 widgets for configuration dialogs |`configwidgets` |KF5 widgets for configuration dialogs |`contacts` |KDE api to manage contact information |`coreaddons` |KF5 addons to QtCore |`crash` |KF5 library to handle crash analysis and bug report from apps |`dbusaddons` |KF5 addons to QtDBus |`decoration` |Plasma5 library to create window decorations |`designerplugin` |KF5 integration of Frameworks widgets in Qt Designer/Creator |`discover` |Plasma5 package management tools |`dnssd` |KF5 abstraction to system DNSSD features |`doctools` |KF5 documentation generation from docbook |`drkonqi` |Plasma5 crash handler |`ecm` |Extra modules and scripts for CMake |`emoticons` |KF5 library to convert emoticons |`eventviews` |Event view libriares for KDEPim |`filemetadata` |KF5 library for extracting file metadata |`frameworkintegration` |KF5 workspace and cross-framework integration plugins |`gapi` |KDE based library to access google services |`globalaccel` |KF5 library to add support for global workspace shortcuts |`grantlee-editor` |Editor for Grantlee themes |`grantleetheme` |KDE PIM grantleetheme |`gravatar` |Library for gravatar support |`guiaddons` |KF5 addons to QtGui |`holidays` |KDE library for calendar holidays |`hotkeys` |Plasma5 library for hotkeys |`i18n` |KF5 advanced internationalization framework |`iconthemes` |KF5 library for handling icons in applications |`identitymanagement` |KDE pim identities |`idletime` |KF5 library for monitoring user activity |`imap` |KDE API for IMAP support |`incidenceeditor` |Incidence editor libriares for KDEPim |`infocenter` |Plasma5 utility providing system information |`init` |KF5 process launcher to speed up launching KDE applications |`itemmodels` |KF5 models for Qt Model/View system |`itemviews` |KF5 widget addons for Qt Model/View |`jobwidgets` |KF5 widgets for tracking KJob instance |`js` |KF5 library providing an ECMAScript interpreter |`jsembed` |KF5 library for binding JavaScript objects to QObjects |`kaddressbook` |KDE contact manager |`kalarm` |Personal alarm scheduler |`kalarm` |Personal alarm scheduler |`kate` |Basic editor framework for the KDE system |`kcmutils` |KF5 utilities for working with KCModules |`kde-cli-tools` |Plasma5 non-interactive system tools |`kde-gtk-config` |Plasma5 GTK2 and GTK3 configurator |`kdeclarative` |KF5 library providing integration of QML and KDE Frameworks |`kded` |KF5 extensible daemon for providing system level services |`kdelibs4support` |KF5 porting aid from KDELibs4 |`kdepim-addons` |KDE PIM addons |`kdepim-apps-libs` |KDE PIM mail related libraries |`kdepim-runtime5` |KDE PIM tools and services |`kdeplasma-addons` |Plasma5 addons to improve the Plasma experience |`kdesu` |KF5 integration with su for elevated privileges |`kdewebkit` |KF5 library providing integration of QtWebKit |`kgamma5` |Plasma5 monitor's gamma settings |`khtml` |KF5 KTHML rendering engine |`kimageformats` |KF5 library providing support for additional image formats |`kio` |KF5 resource and network access abstraction |`kirigami2` |QtQuick based components set |`kitinerary` |Data Model and Extraction System for Travel Reservation information |`kmail` |KDE mail client |`kmail` |KDE mail client |`kmail-account-wizard` |KDE mail account wizard |`kmenuedit` |Plasma5 menu editor |`knotes` |Popup notes |`kontact` |KDE Personal Information Manager |`kontact` |KDE Personal Information Manager |`kontactinterface` |KDE glue for embedding KParts into Kontact |`korganizer` |Calendar and scheduling Program |`kpimdav` |A DAV protocol implementation with KJobs |`kpkpass` |Library to deal with Apple Wallet pass files |`kross` |KF5 multi-language application scripting |`kscreen` |Plasma5 screen management library |`kscreenlocker` |Plasma5 secure lock screen architecture |`ksmtp` |Job-based library to send email through an SMTP server |`ksshaskpass` |Plasma5 ssh-add frontend |`ksysguard` |Plasma5 utility to track and control the running processes |`kwallet-pam` |Plasma5 KWallet PAM Integration |`kwayland-integration` |Integration plugins for a Wayland-based desktop |`kwin` |Plasma5 window manager |`kwrited` |Plasma5 daemon listening for wall and write messages |`ldap` |LDAP access API for KDE |`libkcddb` |KDE CDDB library |`libkcompactdisc` |KDE library for interfacing with audio CDs |`libkdcraw` |LibRaw interface for KDE |`libkdegames` |Libraries used by KDE games |`libkdepim` |KDE PIM Libraries |`libkeduvocdocument` |Library for reading and writing vocabulary files |`libkexiv2` |Exiv2 library interface for KDE |`libkipi` |KDE Image Plugin Interface |`libkleo` |Certificate manager for KDE |`libksane` |SANE library interface for KDE |`libkscreen` |Plasma5 screen management library |`libksieve` |Sieve libriares for KDEPim |`libksysguard` |Plasma5 library to track and control running processes |`mailcommon` |Common libriares for KDEPim |`mailimporter` |Import mbox files to KMail |`mailtransport` |KDE library to managing mail transport |`marble` |Virtual globe and world atlas for KDE |`mbox` |KDE library for accessing mail storages in MBox format |`mbox-importer` |Import mbox files to KMail |`mediaplayer` |KF5 plugin interface for media player features |`messagelib` |Library for handling messages |`milou` |Plasma5 Plasmoid for search |`mime` |Library for handling MIME data |`newstuff` |KF5 library for downloading application assets from the network |`notifications` |KF5 abstraction for system notifications |`notifyconfig` |KF5 configuration system for KNotify |`okular` |KDE universal document viewer |`oxygen` |Plasma5 Oxygen style |`oxygen-icons5` |The Oxygen icon theme for KDE |`package` |KF5 library to load and install packages |`parts` |KF5 document centric plugin system |`people` |KF5 library providing access to contacts |`pim-data-exporter` |Import and export KDE PIM settings |`pimcommon` |Common libriares for KDEPim |`pimtextedit` |KDE library for PIM-specific text editing utilities |`plasma-browser-integration` |Plasma5 components to integrate browsers into the desktop |`plasma-desktop` |Plasma5 plasma desktop |`plasma-framework` |KF5 plugin based UI runtime used to write user interfaces |`plasma-integration` |Qt Platform Theme integration plugins for the Plasma workspaces |`plasma-pa` |Plasma5 Plasma pulse audio mixer |`plasma-sdk` |Plasma5 applications useful for Plasma development |`plasma-workspace` |Plasma5 Plasma workspace |`plasma-workspace-wallpapers` |Plasma5 wallpapers |`plotting` |KF5 lightweight plotting framework |`polkit-kde-agent-1` |Plasma5 daemon providing a polkit authentication UI |`powerdevil` |Plasma5 tool to manage the power consumption settings |`prison` |API to produce barcodes |`pty` |KF5 pty abstraction |`purpose` |Offers available actions for a specific purpose |`qqc2-desktop-style` |Qt QuickControl2 style for KDE |`runner` |KF5 parallelized query system |`service` |KF5 advanced plugin and service introspection |`solid` |KF5 hardware integration and detection |`sonnet` |KF5 plugin-based spell checking library |`syndication` |KDE RSS feed handling library |`syntaxhighlighting` |KF5 syntax highlighting engine for structured text and code |`systemsettings` |Plasma5 system settings |`texteditor` |KF5 advanced embeddable text editor |`textwidgets` |KF5 advanced text editing widgets |`threadweaver` |KF5 addons to QtDBus |`tnef` |KDE API for the handling of TNEF data |`unitconversion` |KF5 library for unit conversion |`user-manager` |Plasma5 user manager |`wallet` |KF5 secure and unified container for user passwords |`wayland` |KF5 Client and Server library wrapper for the Wayland libraries |`widgetsaddons` |KF5 addons to QtWidgets |`windowsystem` |KF5 library for access to the windowing system |`xmlgui` |KF5 user configurable main windows |`xmlrpcclient` |KF5 interaction with XMLRPC services |=== [[kde5-components-example]] .`USE_KDE` Example [example] ==== This is a simple example for a KDE port. `USES= cmake` instructs the port to utilize CMake, a configuration tool widely used by KDE projects (see <> for detailed usage). `USE_KDE` brings dependency on KDE libraries. Required KDE components and other dependencies can be determined through the configure log. `USE_KDE` does not imply `USE_QT`. If a port requires some Qt components, specify them in `USE_QT`. [.programlisting] .... USES= cmake kde:5 qt:5 USE_KDE= ecm USE_QT= core buildtools_build qmake_build .... ==== [[using-lxqt]] == Using LXQt Applications depending on LXQt should set `USES+= lxqt` and set `USE_LXQT` to the list of required components from the table below [[using-lxqt-components]] .Available LXQt Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`buildtools` |Helpers for additional CMake modules |`libfmqt` |Libfm Qt bindings |`lxqt` |LXQt core library |`qtxdg` |Qt implementation of freedesktop.org XDG specifications |=== [[lxqt-components-example]] .`USE_LXQT` Example [example] ==== This is a simple example, `USE_LXQT` adds a dependency on LXQt libraries. Required LXQt components and other dependencies can be determined from the configure log. [.programlisting] .... USES= cmake lxqt qt:5 tar:xz USE_QT= core dbus widgets buildtools_build qmake_build USE_LXQT= buildtools libfmqt .... ==== [[using-java]] == Using Java [[java-variables]] === Variable Definitions If the port needs a Java(TM) Development Kit (JDK(TM)) to either build, run or even extract the distfile, then define `USE_JAVA`. There are several JDKs in the ports collection, from various vendors, and in several versions. If the port must use a particular version, specify it using the `JAVA_VERSION` variable. The most current version is package:java/openjdk16[], with package:java/openjdk15[], package:java/openjdk14[], package:java/openjdk13[], package:java/openjdk12[], package:java/openjdk11[], package:java/openjdk8[], and package:java/openjdk7[] also available. [[using-java-variables]] .Variables Which May be Set by Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`USE_JAVA` |Define for the remaining variables to have any effect. |`JAVA_VERSION` |List of space-separated suitable Java versions for the port. An optional `"+"` allows specifying a range of versions (allowed values: `7[+] 8[+] 11[+] 12[+] 13[+] 14[+] 15[+] 16[+]`). |`JAVA_OS` |List of space-separated suitable JDK port operating systems for the port (allowed values: `native linux`). |`JAVA_VENDOR` |List of space-separated suitable JDK port vendors for the port (allowed values: `openjdk oracle`). |`JAVA_BUILD` |When set, add the selected JDK port to the build dependencies. |`JAVA_RUN` |When set, add the selected JDK port to the run dependencies. |`JAVA_EXTRACT` |When set, add the selected JDK port to the extract dependencies. |=== Below is the list of all settings a port will receive after setting `USE_JAVA`: [[using-java-variables2]] .Variables Provided to Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Variable | Value |`JAVA_PORT` |The name of the JDK port (for example, `java/openjdk6`). |`JAVA_PORT_VERSION` |The full version of the JDK port (for example, `1.6.0`). Only the first two digits of this version number are needed, use `${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}`. |`JAVA_PORT_OS` |The operating system used by the JDK port (for example, `'native'`). |`JAVA_PORT_VENDOR` |The vendor of the JDK port (for example, `'openjdk'`). |`JAVA_PORT_OS_DESCRIPTION` |Description of the operating system used by the JDK port (for example, `'Native'`). |`JAVA_PORT_VENDOR_DESCRIPTION` |Description of the vendor of the JDK port (for example, `'OpenJDK BSD Porting Team'`). |`JAVA_HOME` |Path to the installation directory of the JDK (for example, [.filename]#'/usr/local/openjdk6'#). |`JAVAC` |Path to the Java compiler to use (for example, [.filename]#'/usr/local/openjdk6/bin/javac'#). |`JAR` |Path to the `jar` tool to use (for example, [.filename]#'/usr/local/openjdk6/bin/jar'# or [.filename]#'/usr/local/bin/fastjar'#). |`APPLETVIEWER` |Path to the `appletviewer` utility (for example, [.filename]#'/usr/local/openjdk6/bin/appletviewer'#). |`JAVA` |Path to the `java` executable. Use this for executing Java programs (for example, [.filename]#'/usr/local/openjdk6/bin/java'#). |`JAVADOC` |Path to the `javadoc` utility program. |`JAVAH` |Path to the `javah` program. |`JAVAP` |Path to the `javap` program. |`JAVA_KEYTOOL` |Path to the `keytool` utility program. |`JAVA_N2A` |Path to the `native2ascii` tool. |`JAVA_POLICYTOOL` |Path to the `policytool` program. |`JAVA_SERIALVER` |Path to the `serialver` utility program. |`RMIC` |Path to the RMI stub/skeleton generator, `rmic`. |`RMIREGISTRY` |Path to the RMI registry program, `rmiregistry`. |`RMID` |Path to the RMI daemon program `rmid`. |`JAVA_CLASSES` |Path to the archive that contains the JDK class files, [.filename]#${JAVA_HOME}/jre/lib/rt.jar#. |=== Use the `java-debug` make target to get information for debugging the port. It will display the value of many of the previously listed variables. Additionally, these constants are defined so all Java ports may be installed in a consistent way: [[using-java-constants]] .Constants Defined for Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Constant | Value |`JAVASHAREDIR` |The base directory for everything related to Java. Default: [.filename]#${PREFIX}/share/java#. |`JAVAJARDIR` |The directory where JAR files is installed. Default: [.filename]#${JAVASHAREDIR}/classes#. |`JAVALIBDIR` |The directory where JAR files installed by other ports are located. Default: [.filename]#${LOCALBASE}/share/java/classes#. |=== -The related entries are defined in both `PLIST_SUB` (documented in <>) and `SUB_LIST`. +The related entries are defined in both `PLIST_SUB` (documented in crossref:plist[plist-sub,Changing pkg-plist Based on Make Variables]) and `SUB_LIST`. [[java-building-with-ant]] === Building with Ant When the port is to be built using Apache Ant, it has to define `USE_ANT`. Ant is thus considered to be the sub-make command. When no `do-build` target is defined by the port, a default one will be set that runs Ant according to `MAKE_ENV`, `MAKE_ARGS` and `ALL_TARGET`. This is similar to the `USES= gmake` mechanism, which is documented in <>. [[java-best-practices]] === Best Practices When porting a Java library, the port has to install the JAR file(s) in [.filename]#${JAVAJARDIR}#, and everything else under [.filename]#${JAVASHAREDIR}/${PORTNAME}# (except for the documentation, see below). To reduce the packing file size, reference the JAR file(s) directly in the [.filename]#Makefile#. Use this statement (where [.filename]#myport.jar# is the name of the JAR file installed as part of the port): [.programlisting] .... PLIST_FILES+= ${JAVAJARDIR}/myport.jar .... When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of [.filename]#${JAVASHAREDIR}/${PORTNAME}# is strongly encouraged in this regard. It is up the porter to decide whether the port installs the additional JAR dependencies under this directory or uses the already installed ones (from [.filename]#${JAVAJARDIR}#). When porting a Java(TM) application that requires an application server such as package:www/tomcat7[] to run the service, it is quite common for a vendor to distribute a [.filename]#.war#. A [.filename]#.war# is a Web application ARchive and is extracted when called by the application. Avoid adding a [.filename]#.war# to [.filename]#pkg-plist#. It is not considered best practice. An application server will expand war archive, but not clean it up properly if the port is removed. A more desirable way of working with this file is to extract the archive, then install the files, and lastly add these files to [.filename]#pkg-plist#. [.programlisting] .... TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 WEBAPPDIR= myapplication post-extract: @${MKDIR} ${WRKDIR}/${PORTDIRNAME} @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} do-install: cd ${WRKDIR} && \ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME} .... Regardless of the type of port (library or application), the additional documentation is installed in the crossref:makefiles[install-documentation,same location] as for any other port. The Javadoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list ([.filename]#pkg-plist#). This is one reason why porters are strongly encouraged to use `PORTDOCS`. Moreover, even if the set of files that will be generated by `javadoc` can be predicted, the size of the resulting [.filename]#pkg-plist# advocates for the use of `PORTDOCS`. The default value for `DATADIR` is [.filename]#${PREFIX}/share/${PORTNAME}#. It is a good idea to override `DATADIR` to [.filename]#${JAVASHAREDIR}/${PORTNAME}# for Java ports. Indeed, `DATADIR` is automatically added to `PLIST_SUB` (documented in crossref:plist[plist-sub,Changing pkg-plist Based on Make Variables]) so use `%%DATADIR%%` directly in [.filename]#pkg-plist#. As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the https://www.freebsd.org/java/[FreeBSD Java Project] encourage porters to have their ports built from source whenever it is a trivial task. All the features that have been presented in this section are implemented in [.filename]#bsd.java.mk#. If the port needs more sophisticated Java support, please first have a look at the https://cgit.FreeBSD.org/ports/tree/Mk/bsd.java.mk[bsd.java.mk Git log] as it usually takes some time to document the latest features. Then, if the needed support that is lacking would be beneficial to many other Java ports, feel free to discuss it on the freebsd-java. Although there is a `java` category for PRs, it refers to the JDK porting effort from the FreeBSD Java project. Therefore, submit the Java port in the `ports` category as for any other port, unless the issue is related to either a JDK implementation or [.filename]#bsd.java.mk#. Similarly, there is a defined policy regarding the `CATEGORIES` of a Java port, which is detailed in crossref:makefiles[makefile-categories,Categorization]. [[using-php]] == Web Applications, Apache and PHP [[using-apache]] === Apache [[using-apache-variables]] .Variables for Ports That Use Apache [cols="1,1", frame="none"] |=== |`USE_APACHE` |The port requires Apache. Possible values: `yes` (gets any version), `22`, `24`, `22-24`, `22+`, etc. The default APACHE version is `22`. More details are available in [.filename]#ports/Mk/bsd.apache.mk# and at https://wiki.freebsd.org/Apache/[wiki.freebsd.org/Apache/]. |`APXS` |Full path to the `apxs` binary. Can be overridden in the port. |`HTTPD` |Full path to the `httpd` binary. Can be overridden in the port. |`APACHE_VERSION` |The version of present Apache installation (read-only variable). This variable is only available after inclusion of [.filename]#bsd.port.pre.mk#. Possible values: `22`, `24`. |`APACHEMODDIR` |Directory for Apache modules. This variable is automatically expanded in [.filename]#pkg-plist#. |`APACHEINCLUDEDIR` |Directory for Apache headers. This variable is automatically expanded in [.filename]#pkg-plist#. |`APACHEETCDIR` |Directory for Apache configuration files. This variable is automatically expanded in [.filename]#pkg-plist#. |=== [[using-apache-modules]] .Useful Variables for Porting Apache Modules [cols="1,1", frame="none"] |=== |`MODULENAME` |Name of the module. Default value is `PORTNAME`. Example: `mod_hello` |`SHORTMODNAME` |Short name of the module. Automatically derived from `MODULENAME`, but can be overridden. Example: `hello` |`AP_FAST_BUILD` |Use `apxs` to compile and install the module. |`AP_GENPLIST` |Also automatically creates a [.filename]#pkg-plist#. |`AP_INC` |Adds a directory to a header search path during compilation. |`AP_LIB` |Adds a directory to a library search path during compilation. |`AP_EXTRAS` |Additional flags to pass to `apxs`. |=== [[web-apps]] === Web Applications Web applications must be installed into [.filename]#PREFIX/www/appname#. This path is available both in [.filename]#Makefile# and in [.filename]#pkg-plist# as `WWWDIR`, and the path relative to `PREFIX` is available in [.filename]#Makefile# as `WWWDIR_REL`. The user and group of web server process are available as `WWWOWN` and `WWWGRP`, in case the ownership of some files needs to be changed. The default values of both are `www`. Use `WWWOWN?= myuser` and `WWWGRP?= mygroup` if the port needs different values. This allows the user to override them easily. [IMPORTANT] ==== Use `WWWOWN` and `WWWGRP` sparingly. Remember that every file the web server can write to is a security risk waiting to happen. ==== Do not depend on Apache unless the web app explicitly needs Apache. Respect that users may wish to run a web application on a web server other than Apache. [[php-variables]] === PHP PHP web applications declare their dependency on it with `USES=php`. See crossref:uses[uses-php,`php`] for more information. [[php-pear]] === PEAR Modules Porting PEAR modules is a very simple process. Add `USES=pear` to the port's [.filename]#Makefile#. The framework will install the relevant files in the right places and automatically generate the plist at install time. [[pear-makefile]] .Example Makefile for PEAR Class [example] ==== [.programlisting] .... PORTNAME= Date DISTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= example@domain.com COMMENT= PEAR Date and Time Zone Classes USES= pear .include .... ==== [TIP] ==== PEAR modules will automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors]. ==== [NOTE] ==== If a non default `PEAR_CHANNEL` is used, the build and run-time dependencies will automatically be added. ==== [IMPORTANT] ==== PEAR modules do not need to defined `PKGNAMESUFFIX` it is automatically filled in using `PEAR_PKGNAMEPREFIX`. If a port needs to add to `PKGNAMEPREFIX`, it must also use `PEAR_PKGNAMEPREFIX` to differentiate between different flavors. ==== [[php-horde]] ==== Horde Modules In the same way, porting Horde modules is a simple process. Add `USES=horde` to the port's [.filename]#Makefile#. The framework will install the relevant files in the right places and automatically generate the plist at install time. The `USE_HORDE_BUILD` and `USE_HORDE_RUN` variables can be used to add buildtime and runtime dependencies on other Horde modules. See [.filename]#Mk/Uses/horde.mk# for a complete list of available modules. [[horde-Makefile]] .Example Makefile for Horde Module [example] ==== [.programlisting] .... PORTNAME= Horde_Core DISTVERSION= 2.14.0 CATEGORIES= devel www pear MAINTAINER= horde@FreeBSD.org COMMENT= Horde Core Framework libraries OPTIONS_DEFINE= KOLAB SOCKETS KOLAB_DESC= Enable Kolab server support SOCKETS_DESC= Depend on sockets PHP extension USES= horde USE_PHP= session USE_HORDE_BUILD= Horde_Role USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \ Horde_Text_Filter Horde_View KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session SOCKETS_USE= PHP=sockets .include .... ==== [TIP] ==== As Horde modules are also PEAR modules they will also automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors]. ==== [[using-python]] == Using Python The Ports Collection supports parallel installation of multiple Python versions. Ports must use a correct `python` interpreter, according to the user-settable `PYTHON_VERSION`. Most prominently, this means replacing the path to `python` executable in scripts with the value of `PYTHON_CMD`. Ports that install files under `PYTHON_SITELIBDIR` must use the `pyXY-` package name prefix, so their package name embeds the version of Python they are installed into. [.programlisting] .... PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} .... [[using-python-variables]] .Most Useful Variables for Ports That Use Python [cols="1,1", frame="none"] |=== |`USES=python` |The port needs Python. The minimal required version can be specified with values such as `2.7+`. Version ranges can also be specified by separating two version numbers with a dash: `USES=python:3.2-3.3` |`USE_PYTHON=distutils` |Use Python distutils for configuring, compiling, and installing. This is required when the port comes with [.filename]#setup.py#. This overrides the `do-build` and `do-install` targets and may also override `do-configure` if `GNU_CONFIGURE` is not defined. Additionally, it implies `USE_PYTHON=flavors`. |`USE_PYTHON=autoplist` |Create the packaging list automatically. This also requires `USE_PYTHON=distutils` to be set. |`USE_PYTHON=concurrent` |The port will use an unique prefix, typically `PYTHON_PKGNAMEPREFIX` for certain directories, such as `EXAMPLESDIR` and `DOCSDIR` and also will append a suffix, the python version from `PYTHON_VER`, to binaries and scripts to be installed. This allows ports to be installed for different Python versions at the same time, which otherwise would install conflicting files. |`USE_PYTHON=flavors` |The port does not use distutils but still supports multiple Python versions. `FLAVORS` will be set to the supported Python versions. See crossref:flavors[flavors-auto-python,`USES`=python and Flavors] for more information. |`USE_PYTHON=optsuffix` |If the current Python version is not the default version, the port will gain `PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}`. Only useful with flavors. |`PYTHON_PKGNAMEPREFIX` |Used as a `PKGNAMEPREFIX` to distinguish packages for different Python versions. Example: `py27-` |`PYTHON_SITELIBDIR` |Location of the site-packages tree, that contains installation path of Python (usually `LOCALBASE`). `PYTHON_SITELIBDIR` can be very useful when installing Python modules. |`PYTHONPREFIX_SITELIBDIR` |The PREFIX-clean variant of PYTHON_SITELIBDIR. Always use `%%PYTHON_SITELIBDIR%%` in [.filename]#pkg-plist# when possible. The default value of `%%PYTHON_SITELIBDIR%%` is `lib/python%%PYTHON_VERSION%%/site-packages` |`PYTHON_CMD` |Python interpreter command line, including version number. |=== [[using-python-variables-helpers]] .Python Module Dependency Helpers [cols="1,1", frame="none"] |=== |`PYNUMERIC` |Dependency line for numeric extension. |`PYNUMPY` |Dependency line for the new numeric extension, numpy. (PYNUMERIC is deprecated by upstream vendor). |`PYXML` |Dependency line for XML extension (not needed for Python 2.0 and higher as it is also in base distribution). |`PY_ENUM34` |Conditional dependency on package:devel/py-enum34[] depending on the Python version. |`PY_ENUM_COMPAT` |Conditional dependency on package:devel/py-enum-compat[] depending on the Python version. |`PY_PATHLIB` |Conditional dependency on package:devel/py-pathlib[] depending on the Python version. |`PY_IPADDRESS` |Conditional dependency on package:net/py-ipaddress[] depending on the Python version. |`PY_FUTURES` |Conditional dependency on package:devel/py-futures[] depending on the Python version. |=== A complete list of available variables can be found in [.filename]#/usr/ports/Mk/Uses/python.mk#. [IMPORTANT] ==== All dependencies to Python ports using crossref:flavors[flavors-auto-python,Python flavors] (either with `USE_PYTHON=distutils` or `USE_PYTHON=flavors`) must have the Python flavor appended to their origin using `@${PY_FLAVOR}`. See <>. ==== [[python-Makefile]] .Makefile for a Simple Python Module [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= devel MAINTAINER= john@doe.tld COMMENT= Python sample module RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} USES= python USE_PYTHON= autoplist distutils .include .... ==== Some Python applications claim to have `DESTDIR` support (which would be required for staging) but it is broken (Mailman up to 2.1.16, for instance). This can be worked around by recompiling the scripts. This can be done, for example, in the `post-build` target. Assuming the Python scripts are supposed to reside in `PYTHONPREFIX_SITELIBDIR` after installation, this solution can be applied: [.programlisting] .... (cd ${STAGEDIR}${PREFIX} \ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;}) .... This recompiles the sources with a path relative to the stage directory, and prepends the value of `PREFIX` to the file name recorded in the byte-compiled output file by `-d`. `-f` is required to force recompilation, and the `:S;${PREFIX}/;;` strips prefixes from the value of `PYTHONPREFIX_SITELIBDIR` to make it relative to `PREFIX`. [[using-tcl]] == Using Tcl/Tk The Ports Collection supports parallel installation of multiple Tcl/Tk versions. Ports should try to support at least the default Tcl/Tk version and higher with `USES=tcl`. It is possible to specify the desired version of `tcl` by appending `:_xx_`, for example, `USES=tcl:85`. [[using-tcl-variables]] .The Most Useful Read-Only Variables for Ports That Use Tcl/Tk [cols="1,1", frame="none"] |=== |`TCL_VER` | chosen major.minor version of Tcl |`TCLSH` | full path of the Tcl interpreter |`TCL_LIBDIR` | path of the Tcl libraries |`TCL_INCLUDEDIR` | path of the Tcl C header files |`TK_VER` | chosen major.minor version of Tk |`WISH` | full path of the Tk interpreter |`TK_LIBDIR` | path of the Tk libraries |`TK_INCLUDEDIR` | path of the Tk C header files |=== See the crossref:uses[uses-tcl,`USES=tcl`] and crossref:uses[uses-tk,`USES=tk`] of crossref:uses[uses,Using `USES` Macros] for a full description of those variables. A complete list of those variables is available in [.filename]#/usr/ports/Mk/Uses/tcl.mk#. [[using-ruby]] == Using Ruby [[using-ruby-variables]] .Useful Variables for Ports That Use Ruby [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`USE_RUBY` |Adds build and run dependencies on Ruby. |`USE_RUBY_EXTCONF` |The port uses [.filename]#extconf.rb# to configure. |`USE_RUBY_SETUP` |The port uses [.filename]#setup.rb# to configure. |`RUBY_SETUP` |Override the name of the setup script from [.filename]#setup.rb#. Another common value is [.filename]#install.rb#. |=== This table shows the selected variables available to port authors via the ports infrastructure. These variables are used to install files into their proper locations. Use them in [.filename]#pkg-plist# as much as possible. Do not redefine these variables in the port. [[using-ruby-variables-ro]] .Selected Read-Only Variables for Ports That Use Ruby [cols="1,1,1", frame="none", options="header"] |=== | Variable | Description | Example value |`RUBY_PKGNAMEPREFIX` |Used as a `PKGNAMEPREFIX` to distinguish packages for different Ruby versions. |`ruby19-` |`RUBY_VERSION` |Full version of Ruby in the form of `x.y.z[.p]`. |`1.9.3.484` |`RUBY_SITELIBDIR` |Architecture independent libraries installation path. |`/usr/local/lib/ruby/site_ruby/1.9` |`RUBY_SITEARCHLIBDIR` |Architecture dependent libraries installation path. |`/usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10` |`RUBY_MODDOCDIR` |Module documentation installation path. |`/usr/local/share/doc/ruby19/patsy` |`RUBY_MODEXAMPLESDIR` |Module examples installation path. |`/usr/local/share/examples/ruby19/patsy` |=== A complete list of available variables can be found in [.filename]#/usr/ports/Mk/bsd.ruby.mk#. [[using-sdl]] == Using SDL `USE_SDL` is used to autoconfigure the dependencies for ports which use an SDL based library like package:devel/sdl12[] and package:graphics/sdl_image[]. These SDL libraries for version 1.2 are recognized: * sdl: package:devel/sdl12[] * console: package:devel/sdl_console[] * gfx: package:graphics/sdl_gfx[] * image: package:graphics/sdl_image[] * mixer: package:audio/sdl_mixer[] * mm: package:devel/sdlmm[] * net: package:net/sdl_net[] * pango: package:x11-toolkits/sdl_pango[] * sound: package:audio/sdl_sound[] * ttf: package:graphics/sdl_ttf[] These SDL libraries for version 2.0 are recognized: * sdl: package:devel/sdl20[] * gfx: package:graphics/sdl2_gfx[] * image: package:graphics/sdl2_image[] * mixer: package:audio/sdl2_mixer[] * net: package:net/sdl2_net[] * ttf: package:graphics/sdl2_ttf[] Therefore, if a port has a dependency on package:net/sdl_net[] and package:audio/sdl_mixer[], the syntax will be: [.programlisting] .... USE_SDL= net mixer .... The dependency package:devel/sdl12[], which is required by package:net/sdl_net[] and package:audio/sdl_mixer[], is automatically added as well. Using `USE_SDL` with entries for SDL 1.2, it will automatically: * Add a dependency on sdl12-config to `BUILD_DEPENDS` * Add the variable `SDL_CONFIG` to `CONFIGURE_ENV` * Add the dependencies of the selected libraries to `LIB_DEPENDS` Using `USE_SDL` with entries for SDL 2.0, it will automatically: * Add a dependency on sdl2-config to `BUILD_DEPENDS` * Add the variable `SDL2_CONFIG` to `CONFIGURE_ENV` * Add the dependencies of the selected libraries to `LIB_DEPENDS` [[using-wx]] == Using wxWidgets This section describes the status of the wxWidgets libraries in the ports tree and its integration with the ports system. [[wx-introduction]] === Introduction There are many versions of the wxWidgets libraries which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes. The obvious disadvantage of this is that each application has to be modified to find the expected version. Fortunately, most of the applications call the `wx-config` script to determine the necessary compiler and linker flags. The script is named differently for every available version. Majority of applications respect an environment variable, or accept a configure argument, to specify which `wx-config` script to call. Otherwise they have to be patched. [[wx-version]] === Version Selection To make the port use a specific version of wxWidgets there are two variables available for defining (if only one is defined the other will be set to a default value): [[wx-ver-sel-table]] .Variables to Select wxWidgets Versions [cols="1,1,1", frame="none", options="header"] |=== | Variable | Description | Default value |`USE_WX` |List of versions the port can use |All available versions |`USE_WX_NOT` |List of versions the port cannot use |None |=== The available wxWidgets versions and the corresponding ports in the tree are: [[wx-widgets-versions-table]] .Available wxWidgets Versions [cols="1,1", frame="none", options="header"] |=== | Version | Port |`2.8` |package:x11-toolkits/wxgtk28[] |`3.0` |package:x11-toolkits/wxgtk30[] |=== The variables in <> can be set to one or more of these combinations separated by spaces: [[wx-widgets-versions-specification]] .wxWidgets Version Specifications [cols="1,1", frame="none", options="header"] |=== | Description | Example |Single version |`2.8` |Ascending range |`2.8+` |Descending range |`3.0-` |Full range (must be ascending) |`2.8-3.0` |=== There are also some variables to select the preferred versions from the available ones. They can be set to a list of versions, the first ones will have higher priority. [[wx-widgets-preferred-version]] .Variables to Select Preferred wxWidgets Versions [cols="1,1", frame="none", options="header"] |=== | Name | Designed for |`WANT_WX_VER` |the port |`WITH_WX_VER` |the user |=== [[wx-components]] === Component Selection There are other applications that, while not being wxWidgets libraries, are related to them. These applications can be specified in `WX_COMPS`. These components are available: [[wx-widgets-components-table]] .Available wxWidgets Components [cols="1,1,1", frame="none", options="header"] |=== | Name | Description | Version restriction |`wx` |main library |none |`contrib` |contributed libraries |`none` |`python` |wxPython (Python bindings) |`2.8-3.0` |=== The dependency type can be selected for each component by adding a suffix separated by a semicolon. If not present then a default type will be used (see <>). These types are available: [[wx-widgets-dependency-table]] .Available wxWidgets Dependency Types [cols="1,1", frame="none", options="header"] |=== | Name | Description |`build` |Component is required for building, equivalent to `BUILD_DEPENDS` |`run` |Component is required for running, equivalent to `RUN_DEPENDS` |`lib` |Component is required for building and running, equivalent to `LIB_DEPENDS` |=== The default values for the components are detailed in this table: [[wx-def-dep-types]] .Default wxWidgets Dependency Types [cols="1,1", frame="none", options="header"] |=== | Component | Dependency type |`wx` |`lib` |`contrib` |`lib` |`python` |`run` |`mozilla` |`lib` |`svg` |`lib` |=== [[wx-components-example]] .Selecting wxWidgets Components [example] ==== This fragment corresponds to a port which uses wxWidgets version `2.4` and its contributed libraries. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx contrib .... ==== [[wx-version-detection]] === Detecting Installed Versions To detect an installed version, define `WANT_WX`. If it is not set to a specific version then the components will have a version suffix. `HAVE_WX` will be filled after detection. [[wx-ver-det-example]] .Detecting Installed wxWidgets Versions and Components [example] ==== This fragment can be used in a port that uses wxWidgets if it is installed, or an option is selected. [.programlisting] .... WANT_WX= yes .include .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8) USE_WX= 2.8 CONFIGURE_ARGS+= --enable-wx .endif .... This fragment can be used in a port that enables wxPython support if it is installed or if an option is selected, in addition to wxWidgets, both version `2.8`. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx WANT_WX= 2.8 .include .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif .... ==== [[wx-defined-variables]] === Defined Variables These variables are available in the port (after defining one from <>). [[wx-widgets-variables]] .Variables Defined for Ports That Use wxWidgets [cols="1,1", frame="none", options="header"] |=== | Name | Description |`WX_CONFIG` |The path to the wxWidgets`wx-config` script (with different name) |`WXRC_CMD` |The path to the wxWidgets`wxrc` program (with different name) |`WX_VERSION` |The wxWidgets version that is going to be used (for example, `2.6`) |=== [[wx-premk]] === Processing in [.filename]#bsd.port.pre.mk# Define `WX_PREMK` to be able to use the variables right after including [.filename]#bsd.port.pre.mk#. [IMPORTANT] ==== When defining `WX_PREMK`, then the version, dependencies, components and defined variables will not change if modifying the wxWidgets port variables _after_ including [.filename]#bsd.port.pre.mk#. ==== [[wx-premk-example]] .Using wxWidgets Variables in Commands [example] ==== This fragment illustrates the use of `WX_PREMK` by running the `wx-config` script to obtain the full version string, assign it to a variable and pass it to the program. [.programlisting] .... USE_WX= 2.8 WX_PREMK= yes .include .if exists(${WX_CONFIG}) VER_STR!= ${WX_CONFIG} --release PLIST_SUB+= VERSION="${VER_STR}" .endif .... ==== [NOTE] ==== The wxWidgets variables can be safely used in commands when they are inside targets without the need of `WX_PREMK`. ==== [[wx-additional-config-args]] === Additional `configure` Arguments Some GNU `configure` scripts cannot find wxWidgets with just the `WX_CONFIG` environment variable set, requiring additional arguments. `WX_CONF_ARGS` can be used for provide them. [[wx-conf-args-values]] .Legal Values for `WX_CONF_ARGS` [cols="1,1", frame="none", options="header"] |=== | Possible value | Resulting argument |`absolute` |`--with-wx-config=${WX_CONFIG}` |`relative` |`--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}` |=== [[using-lua]] == Using Lua This section describes the status of the Lua libraries in the ports tree and its integration with the ports system. [[lua-introduction]] === Introduction There are many versions of the Lua libraries and corresponding interpreters, which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes. The obvious disadvantage of this is that each application has to be modified to find the expected version. But it can be solved by adding some additional flags to the compiler and linker. Applications that use Lua should normally build for just one version. However, loadable modules for Lua are built in a separate flavor for each Lua version that they support, and dependencies on such modules should specify the flavor using the `@${LUA_FLAVOR}` suffix on the port origin. [[lua-version]] === Version Selection A port using Lua should have a line of this form: [.programlisting] .... USES= lua .... If a specific version of Lua, or range of versions, is needed, it can be specified as a parameter in the form `XY` (which may be used multiple times), `XY+`, `-XY`, or `XY-ZA`. The default version of Lua as set via `DEFAULT_VERSIONS` will be used if it falls in the requested range, otherwise the closest requested version to the default will be used. For example: [.programlisting] .... USES= lua:52-53 .... Note that no attempt is made to adjust the version selection based on the presence of any already-installed Lua version. [NOTE] ==== The `XY+` form of version specification should not be used without careful consideration; the Lua API changes to some extent in every version, and configuration tools like CMake or Autoconf will often fail to work on future versions of Lua until updated to do so. ==== [[lua-version-config]] === Configuration and Compiler flags Software that uses Lua may have been written to auto-detect the Lua version in use. In general ports should override this assumption, and force the use of the specific Lua version selected as described above. Depending on the software being ported, this might require any or all of: * Using `LUA_VER` as part of a parameter to the software's configuration script via `CONFIGURE_ARGS` or `CONFIGURE_ENV` (or equivalent for other build systems); * Adding `-I${LUA_INCDIR}`, `-L${LUA_LIBDIR}`, and `-llua-${LUA_VER}` to `CFLAGS`, `LDFLAGS`, `LIBS` respectively as appropriate; * Patch the software's configuration or build files to select the correct version. [[lua-version-flavors]] === Version Flavors A port which installs a Lua module (rather than an application that simply makes use of Lua) should build a separate flavor for each supported Lua version. This is done by adding the `module` parameter: [.programlisting] .... USES= lua:module .... A version number or range of versions can be specified as well; use a comma to separate parameters. Since each flavor must have a different package name, the variable `LUA_PKGNAMEPREFIX` is provided which will be set to an appropriate value; the intended usage is: [.programlisting] .... PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} .... Module ports should normally install files only to `LUA_MODLIBDIR`, `LUA_MODSHAREDIR`, `LUA_DOCSDIR`, and `LUA_EXAMPLESDIR`, all of which are set up to refer to version-specific subdirectories. Installing any other files must be done with care to avoid conflicts between versions. A port (other than a Lua module) which wishes to build a separate package for each Lua version should use the `flavors` parameter: [.programlisting] .... USES= lua:flavors .... This operates the same way as the `module` parameter described above, but without the assumption that the package should be documented as a Lua module (so `LUA_DOCSDIR` and `LUA_EXAMPLESDIR` are not defined by default). However, the port may choose to define `LUA_DOCSUBDIR` as a suitable subdirectory name (usually the port's `PORTNAME` as long as this does not conflict with the `PORTNAME` of any module), in which case the framework will define both `LUA_DOCSDIR` and `LUA_EXAMPLESDIR`. As with module ports, a flavored port should avoid installing files that would conflict between versions. Typically this is done by adding `LUA_VER_STR` as a suffix to program names (e.g. using crossref:uses[uses-uniquefiles,`uniquefiles`]), and otherwise using either `LUA_VER` or `LUA_VER_STR` as part of any other files or subdirectories used outside of `LUA_MODLIBDIR` and `LUA_MODSHAREDIR`. [[lua-defined-variables]] === Defined Variables These variables are available in the port. [[using-lua-variables-ports]] .Variables Defined for Ports That Use Lua [cols="1,1", frame="none", options="header"] |=== | Name | Description |`LUA_VER` |The Lua version that is going to be used (for example, `5.1`) |`LUA_VER_STR` |The Lua version without the dots (for example, `51`) |`LUA_FLAVOR` |The flavor name corresponding to the selected Lua version, to be used for specifying dependencies |`LUA_BASE` |The prefix that should be used to locate Lua (and components) that are already installed |`LUA_PREFIX` |The prefix where Lua (and components) are to be installed by this port |`LUA_INCDIR` |The directory where Lua header files are installed |`LUA_LIBDIR` |The directory where Lua libraries are installed |`LUA_REFMODLIBDIR` |The directory where Lua module libraries ([.filename]#.so#) that are already installed are to be found |`LUA_REFMODSHAREDIR` |The directory where Lua modules ([.filename]#.lua#) that are already installed are to be found |`LUA_MODLIBDIR` |The directory where Lua module libraries ([.filename]#.so#) are to be installed by this port |`LUA_MODSHAREDIR` |The directory where Lua modules ([.filename]#.lua#) are to be installed by this port |`LUA_PKGNAMEPREFIX` |The package name prefix used by Lua modules |`LUA_CMD` |The name of the Lua interpreter (e.g. `lua53`) |`LUAC_CMD` |The name of the Lua compiler (e.g. `luac53`) |=== These additional variables are available for ports that specified the `module` parameter: [[using-lua-variables-modules]] .Variables Defined for Lua Module Ports [cols="1,1", frame="none", options="header"] |=== | Name | Description |`LUA_DOCSDIR` |the directory to which the module's documentation should be installed. |`LUA_EXAMPLESDIR` |the directory to which the module's example files should be installed. |=== [[lua-examples]] === Examples [[lua-app-Makefile]] .Makefile for an application using Lua [example] ==== This example shows how to reference a Lua module required at run time. Notice that the reference must specify a flavor. [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever MAINTAINER= john@doe.tld COMMENT= Sample RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR} USES= lua .include .... ==== [[lua-mod-Makefile]] .Makefile for a simple Lua module [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} MAINTAINER= john@doe.tld COMMENT= Sample USES= lua:module DOCSDIR= ${LUA_DOCSDIR} .include .... ==== [[using-iconv]] == Using `iconv` FreeBSD has a native `iconv` in the operating system. For software that needs `iconv`, define `USES=iconv`. When a port defines `USES=iconv`, these variables will be available: [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Variable name | Purpose | Port iconv (when using WCHAR_T or //TRANSLIT extensions) | Base iconv |`ICONV_CMD` |Directory where the `iconv` binary resides |`${LOCALBASE}/bin/iconv` |[.filename]#/usr/bin/iconv# |`ICONV_LIB` |`ld` argument to link to [.filename]#libiconv# (if needed) |`-liconv` |(empty) |`ICONV_PREFIX` |Directory where the `iconv` implementation resides (useful for configure scripts) |`${LOCALBASE}` |[.filename]#/usr# |`ICONV_CONFIGURE_ARG` |Preconstructed configure argument for configure scripts |`--with-libiconv-prefix=${LOCALBASE}` |(empty) |`ICONV_CONFIGURE_BASE` |Preconstructed configure argument for configure scripts |`--with-libiconv=${LOCALBASE}` |(empty) |=== These two examples automatically populate the variables with the correct value for systems using package:converters/libiconv[] or the native `iconv` respectively: [[iconv-simple-use]] .Simple `iconv` Usage [example] ==== [.programlisting] .... USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB} .... ==== [[iconv-configure-use]] .`iconv` Usage with `configure` [example] ==== [.programlisting] .... USES= iconv CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG} .... ==== As shown above, `ICONV_LIB` is empty when a native `iconv` is present. This can be used to detect the native `iconv` and respond appropriately. Sometimes a program has an `ld` argument or search path hardcoded in a [.filename]#Makefile# or configure script. This approach can be used to solve that problem: [[iconv-reinplace]] .Fixing Hardcoded `-liconv` [example] ==== [.programlisting] .... USES= iconv post-patch: @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile .... ==== In some cases it is necessary to set alternate values or perform operations depending on whether there is a native `iconv`. [.filename]#bsd.port.pre.mk# must be included before testing the value of `ICONV_LIB`: [[iconv-conditional]] .Checking for Native `iconv` Availability [example] ==== [.programlisting] .... USES= iconv .include post-patch: .if empty(ICONV_LIB) # native iconv detected @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh .endif .include .... ==== [[using-xfce]] == Using Xfce Ports that need Xfce libraries or applications set `USES=xfce`. Specific Xfce library and application dependencies are set with values assigned to `USE_XFCE`. They are defined in [.filename]#/usr/ports/Mk/Uses/xfce.mk#. The possible values are: .Values of `USE_XFCE` garcon:: package:sysutils/garcon[] libexo:: package:x11/libexo[] libgui:: package:x11-toolkits/libxfce4gui[] libmenu:: package:x11/libxfce4menu[] libutil:: package:x11/libxfce4util[] panel:: package:x11-wm/xfce4-panel[] thunar:: package:x11-fm/thunar[] xfconf:: package:x11/xfce4-conf[] [[use-xfce]] .`USES=xfce` Example [example] ==== [.programlisting] .... USES= xfce USE_XFCE= libmenu .... ==== [[use-xfce-gtk2]] .Using Xfce's Own GTK2 Widgets [example] ==== In this example, the ported application uses the GTK2-specific widgets package:x11/libxfce4menu[] and package:x11/xfce4-conf[]. [.programlisting] .... USES= xfce:gtk2 USE_XFCE= libmenu xfconf .... ==== [TIP] ==== Xfce components included this way will automatically include any dependencies they need. It is no longer necessary to specify the entire list. If the port only needs package:x11-wm/xfce4-panel[], use: [.programlisting] .... USES= xfce USE_XFCE= panel .... There is no need to list the components package:x11-wm/xfce4-panel[] needs itself like this: [.programlisting] .... USES= xfce USE_XFCE= libexo libmenu libutil panel .... However, Xfce components and non-Xfce dependencies of the port must be included explicitly. Do not count on an Xfce component to provide a sub-dependency other than itself for the main port. ==== [[using-databases]] == Using Databases Use one of the `USES` macros from <> to add a dependency on a database. [[using-databases-uses]] .Database `USES` Macros [cols="1,1", frame="none", options="header"] |=== | Database | USES Macro |Berkeley DB |crossref:uses[uses-bdb,`bdb`] |MariaDB, MySQL, Percona |crossref:uses[uses-mysql,`mysql`] |PostgreSQL |crossref:uses[uses-pgsql,`pgsql`] |SQLite |crossref:uses[uses-sqlite,`sqlite`] |=== [[using-databases-bdb-ex1]] .Using Berkeley DB 6 [example] ==== [.programlisting] .... USES= bdb:6 .... See crossref:uses[uses-bdb,`bdb`] for more information. ==== [[using-databases-mysql-ex1]] .Using MySQL [example] ==== When a port needs the MySQL client library add [.programlisting] .... USES= mysql .... See crossref:uses[uses-mysql,`mysql`] for more information. ==== [[using-databases-pgsql-ex1]] .Using PostgreSQL [example] ==== When a port needs the PostgreSQL server version 9.6 or later add [.programlisting] .... USES= pgsql:9.6+ WANT_PGSQL= server .... See crossref:uses[uses-pgsql,`pgsql`] for more information. ==== [[using-databases-sqlite-ex1]] .Using SQLite 3 [example] ==== [.programlisting] .... USES= sqlite:3 .... See crossref:uses[uses-sqlite,`sqlite`] for more information. ==== [[rc-scripts]] == Starting and Stopping Services (`rc` Scripts) [.filename]#rc.d# scripts are used to start services on system startup, and to give administrators a standard way of stopping, starting and restarting the service. Ports integrate into the system [.filename]#rc.d# framework. Details on its usage can be found in extref:{handbook}[the rc.d Handbook chapter, configtuning-rcd]. Detailed explanation of the available commands is provided in man:rc[8] and man:rc.subr[8]. Finally, there is extref:{rc-scripting}[an article] on practical aspects of [.filename]#rc.d# scripting. With a mythical port called _doorman_, which needs to start a _doormand_ daemon. Add the following to the [.filename]#Makefile#: [.programlisting] .... USE_RC_SUBR= doormand .... Multiple scripts may be listed and will be installed. Scripts must be placed in the [.filename]#files# subdirectory and a `.in` suffix must be added to their filename. Standard `SUB_LIST` expansions will be ran against this file. Use of the `%%PREFIX%%` and `%%LOCALBASE%%` expansions is strongly encouraged as well. More on `SUB_LIST` in crossref:pkg-files[using-sub-files,the relevant section]. As of FreeBSD 6.1-RELEASE, local [.filename]#rc.d# scripts (including those installed by ports) are included in the overall man:rcorder[8] of the base system. An example simple [.filename]#rc.d# script to start the doormand daemon: [.programlisting] .... #!/bin/sh # $FreeBSD$ # # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown # # Add these lines to /etc/rc.conf.local or /etc/rc.conf # to enable this service: # # doormand_enable (bool): Set to NO by default. # Set it to YES to enable doormand. # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf # by default. . /etc/rc.subr name=doormand rcvar=doormand_enable load_rc_config $name : ${doormand_enable:="NO"} : ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"} command=%%PREFIX%%/sbin/${name} pidfile=/var/run/${name}.pid command_args="-p $pidfile -f $doormand_config" run_rc_command "$1" .... Unless there is a very good reason to start the service earlier, or it runs as a particular user (other than root), all ports scripts must use: [.programlisting] .... REQUIRE: LOGIN .... If the startup script launches a daemon that must be shutdown, the following will trigger a stop of the service on system shutdown: [.programlisting] .... KEYWORD: shutdown .... If the script is not starting a persistent service this is not necessary. For optional configuration elements the "=" style of default variable assignment is preferable to the ":=" style here, since the former sets a default value only if the variable is unset, and the latter sets one if the variable is unset _or_ null. A user might very well include something like: [.programlisting] .... doormand_flags="" .... in their [.filename]#rc.conf.local#, and a variable substitution using ":=" would inappropriately override the user's intention. The `_enable` variable is not optional, and must use the ":" for the default. [IMPORTANT] ==== Ports _must not_ start and stop their services when installing and deinstalling. Do not abuse the [.filename]#plist# keywords described in crossref:plist[plist-keywords-base-exec, "the @preexec command,@postexec command,@preunexec command,@postunexec command section"] by running commands that modify the currently running system, including starting or stopping services. ==== [[rc-scripts-checklist]] === Pre-Commit Checklist Before contributing a port with an [.filename]#rc.d# script, and more importantly, before committing one, please consult this checklist to be sure that it is ready. The package:devel/rclint[] port can check for most of these, but it is not a substitute for proper review. [.procedure] . If this is a new file, does it have a [.filename]#.sh# extension? If so, that must be changed to just [.filename]#file.in# since [.filename]#rc.d# files may not end with that extension. . Does the file have a `$FreeBSD$` tag? . Do the name of the file (minus [.filename]#.in#), the `PROVIDE` line, and `$` _name_ all match? The file name matching `PROVIDE` makes debugging easier, especially for man:rcorder[8] issues. Matching the file name and `$`_name_ makes it easier to figure out which variables are relevant in [.filename]#rc.conf[.local]#. It is also a policy for all new scripts, including those in the base system. . Is the `REQUIRE` line set to `LOGIN`? This is mandatory for scripts that run as a non-root user. If it runs as root, is there a good reason for it to run prior to `LOGIN`? If not, it must run after so that local scrips can be loosely grouped to a point in man:rcorder[8] after most everything in the base is already running. . Does the script start a persistent service? If so, it must have `KEYWORD: shutdown`. . Make sure there is no `KEYWORD: FreeBSD` present. This has not been necessary nor desirable for years. It is also an indication that the new script was copy/pasted from an old script, so extra caution must be given to the review. . If the script uses an interpreted language like `perl`, `python`, or `ruby`, make certain that `command_interpreter` is set appropriately, for example, for Perl, by adding `PERL=${PERL}` to `SUB_LIST` and using `%%PERL%%`. Otherwise, + [source,shell] .... # service name stop .... + will probably not work properly. See man:service[8] for more information. . Have all occurrences of [.filename]#/usr/local# been replaced with `%%PREFIX%%`? . Do the default variable assignments come after `load_rc_config`? . Are there default assignments to empty strings? They should be removed, but double-check that the option is documented in the comments at the top of the file. . Are things that are set in variables actually used in the script? . Are options listed in the default _name_`_flags` things that are actually mandatory? If so, they must be in `command_args`. `-d` is a red flag (pardon the pun) here, since it is usually the option to "daemonize" the process, and therefore is actually mandatory. . `_name__flags` must never be included in `command_args` (and vice versa, although that error is less common). . Does the script execute any code unconditionally? This is frowned on. Usually these things must be dealt with through a `start_precmd`. . All boolean tests must use the `checkyesno` function. No hand-rolled tests for `[Yy][Ee][Ss]`, etc. . If there is a loop (for example, waiting for something to start) does it have a counter to terminate the loop? We do not want the boot to be stuck forever if there is an error. . Does the script create files or directories that need specific permissions, for example, a [.filename]#pid# that needs to be owned by the user that runs the process? Rather than the traditional man:touch[1]/man:chown[8]/man:chmod[1] routine, consider using man:install[1] with the proper command line arguments to do the whole procedure with one step. [[users-and-groups]] == Adding Users and Groups Some ports require a particular user account to be present, usually for daemons that run as that user. For these ports, choose a _unique_ UID from 50 to 999 and register it in [.filename]#ports/UIDs# (for users) and [.filename]#ports/GIDs# (for groups). The unique identification should be the same for users and groups. Please include a patch against these two files when requiring a new user or group to be created for the port. Then use `USERS` and `GROUPS` in [.filename]#Makefile#, and the user will be automatically created when installing the port. [.programlisting] .... USERS= pulse GROUPS= pulse pulse-access pulse-rt .... The current list of reserved UIDs and GIDs can be found in [.filename]#ports/UIDs# and [.filename]#ports/GIDs#. [[requiring-kernel-sources]] == Ports That Rely on Kernel Sources Some ports (such as kernel loadable modules) need the kernel source files so that the port can compile. Here is the correct way to determine if the user has them installed: [.programlisting] .... USES= kmod .... Apart from this check, the `kmod` feature takes care of most items that these ports need to take into account. [[go-libs]] == Go Libraries Ports must not package or install Go libs or source code. Go ports must fetch the required deps at the normal fetch time and should only install the programs and things users need, not the things Go developers would need. Ports should (in order of preference): * Use vendored dependencies included with the package source. * Fetch the versions of deps specified by upstream (in the case of go.mod, vendor.json or similar). * As a last resort (deps are not included nor versions specified exactly) fetch versions of dependencies available at the time of upstream development/release. [[haskell-libs]] == Haskell Libraries Just like in case of Go language, Ports must not package or install Haskell libraries. Haskell ports must link statically to their dependencies and fetch all distribution files on fetch stage. [[shell-completion]] == Shell Completion Files Many modern shells (including bash, fish, tcsh and zsh) support parameter and/or option tab-completion. This support usually comes from completion files, which contain the definitions for how tab completion will work for a certain command. Ports sometimes ship with their own completion files, or porters may have created them themselves. When available, completion files should always be installed. It is not necessary to make an option for it. If an option is used, though, always enable it in `OPTIONS_DEFAULT`. [[shell-completion-paths]] .Shell completion file paths [cols="1,1", frame="none"] |=== |`bash` |[.filename]#${PREFIX}/etc/bash_completion.d# |`fish` |[.filename]#${PREFIX}/share/fish/vendor_completions.d# |`zsh` |[.filename]#${PREFIX}/share/zsh/site-functions# |=== Do not register any dependencies on the shells themselves. diff --git a/documentation/content/pt-br/books/porters-handbook/_index.adoc b/documentation/content/pt-br/books/porters-handbook/_index.adoc index b1f46c3a79..ab02883d70 100644 --- a/documentation/content/pt-br/books/porters-handbook/_index.adoc +++ b/documentation/content/pt-br/books/porters-handbook/_index.adoc @@ -1,70 +1,52 @@ --- title: FreeBSD Porter's Handbook authors: - author: Projeto de Documentação do FreeBSD copyright: 2000-2020 The FreeBSD Documentation Project trademarks: ["freebsd", "sun", "unix", "general"] +next: books/porters-handbook/porting-why +add_single_page_link: true isIndex: true --- = FreeBSD Porter's Handbook :doctype: book :toc: macro -:toclevels: 2 +:toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: -:book: true -:pdf: false +:images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :chapters-path: content/{{% lang %}}/books/porters-handbook/ endif::[] ifdef::backend-pdf,backend-epub3[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' -toc::[] +include::{chapters-path}toc.adoc[] include::{chapters-path}toc-tables.adoc[] -include::{chapters-path}toc-examples.adoc[] - -include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1] -include::{chapters-path}new-port/chapter.adoc[leveloffset=+1] -include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1] -include::{chapters-path}special/chapter.adoc[leveloffset=+1] -include::{chapters-path}flavors/chapter.adoc[leveloffset=+1] -include::{chapters-path}plist/chapter.adoc[leveloffset=+1] -include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1] -include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1] -include::{chapters-path}security/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1] -include::{chapters-path}order/chapter.adoc[leveloffset=+1] -include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1] -include::{chapters-path}uses/chapter.adoc[leveloffset=+1] -include::{chapters-path}versions/chapter.adoc[leveloffset=+1] +include::{chapters-path}toc-examples.adoc[] diff --git a/documentation/content/pt-br/books/porters-handbook/_index.adoc b/documentation/content/pt-br/books/porters-handbook/book.adoc similarity index 50% copy from documentation/content/pt-br/books/porters-handbook/_index.adoc copy to documentation/content/pt-br/books/porters-handbook/book.adoc index b1f46c3a79..b728ab6e06 100644 --- a/documentation/content/pt-br/books/porters-handbook/_index.adoc +++ b/documentation/content/pt-br/books/porters-handbook/book.adoc @@ -1,70 +1,70 @@ --- title: FreeBSD Porter's Handbook authors: - author: Projeto de Documentação do FreeBSD copyright: 2000-2020 The FreeBSD Documentation Project trademarks: ["freebsd", "sun", "unix", "general"] isIndex: true --- = FreeBSD Porter's Handbook :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: :book: true :pdf: false ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :chapters-path: content/{{% lang %}}/books/porters-handbook/ endif::[] ifdef::backend-pdf,backend-epub3[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' toc::[] include::{chapters-path}toc-tables.adoc[] include::{chapters-path}toc-examples.adoc[] -include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1] -include::{chapters-path}new-port/chapter.adoc[leveloffset=+1] -include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1] -include::{chapters-path}special/chapter.adoc[leveloffset=+1] -include::{chapters-path}flavors/chapter.adoc[leveloffset=+1] -include::{chapters-path}plist/chapter.adoc[leveloffset=+1] -include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1] -include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1] -include::{chapters-path}security/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1] -include::{chapters-path}order/chapter.adoc[leveloffset=+1] -include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1] -include::{chapters-path}uses/chapter.adoc[leveloffset=+1] -include::{chapters-path}versions/chapter.adoc[leveloffset=+1] +include::{chapters-path}porting-why/_index.adoc[leveloffset=+1] +include::{chapters-path}new-port/_index.adoc[leveloffset=+1] +include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1] +include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1] +include::{chapters-path}makefiles/_index.adoc[leveloffset=+1] +include::{chapters-path}special/_index.adoc[leveloffset=+1] +include::{chapters-path}flavors/_index.adoc[leveloffset=+1] +include::{chapters-path}plist/_index.adoc[leveloffset=+1] +include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1] +include::{chapters-path}testing/_index.adoc[leveloffset=+1] +include::{chapters-path}upgrading/_index.adoc[leveloffset=+1] +include::{chapters-path}security/_index.adoc[leveloffset=+1] +include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1] +include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1] +include::{chapters-path}order/_index.adoc[leveloffset=+1] +include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1] +include::{chapters-path}uses/_index.adoc[leveloffset=+1] +include::{chapters-path}versions/_index.adoc[leveloffset=+1] diff --git a/documentation/content/pt-br/books/porters-handbook/chapters-order.adoc b/documentation/content/pt-br/books/porters-handbook/chapters-order.adoc index 3aaba51a43..81f5b000cb 100644 --- a/documentation/content/pt-br/books/porters-handbook/chapters-order.adoc +++ b/documentation/content/pt-br/books/porters-handbook/chapters-order.adoc @@ -1,18 +1,18 @@ -porting-why/chapter.adoc -new-port/chapter.adoc -quick-porting/chapter.adoc -slow-porting/chapter.adoc -makefiles/chapter.adoc -special/chapter.adoc -flavors/chapter.adoc -plist/chapter.adoc -pkg-files/chapter.adoc -testing/chapter.adoc -upgrading/chapter.adoc -security/chapter.adoc -porting-dads/chapter.adoc -porting-samplem/chapter.adoc -order/chapter.adoc -keeping-up/chapter.adoc -uses/chapter.adoc -versions/chapter.adoc +porting-why/_index.adoc +new-port/_index.adoc +quick-porting/_index.adoc +slow-porting/_index.adoc +makefiles/_index.adoc +special/_index.adoc +flavors/_index.adoc +plist/_index.adoc +pkg-files/_index.adoc +testing/_index.adoc +upgrading/_index.adoc +security/_index.adoc +porting-dads/_index.adoc +porting-samplem/_index.adoc +order/_index.adoc +keeping-up/_index.adoc +uses/_index.adoc +versions/_index.adoc diff --git a/documentation/content/pt-br/books/porters-handbook/flavors/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/flavors/_index.adoc similarity index 95% rename from documentation/content/pt-br/books/porters-handbook/flavors/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/flavors/_index.adoc index 412309f480..523bd8a36c 100644 --- a/documentation/content/pt-br/books/porters-handbook/flavors/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/flavors/_index.adoc @@ -1,360 +1,360 @@ --- title: Capítulo 7. Flavors prev: books/porters-handbook/special next: books/porters-handbook/plist --- [[flavors]] = Flavors :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 7 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[flavors-intro]] == Uma Introdução aos Flavors Os flavors são uma maneira de ter várias variações de um port. O port é construído várias vezes, com variações. Por exemplo, um port pode ter uma versão normal com muitos recursos e algumas dependências, e uma versão leve "lite" com apenas recursos básicos e dependências mínimas. Outro exemplo poderia ser, um port pode ter um flavor GTK e um QT, dependendo de qual kit de ferramentas ele usa. [[flavors-using]] == Usando FLAVORS Para declarar um port com vários flavors, adicione `FLAVORS` no seu [.filename]#Makefile#. O primeiro flavor em `FLAVORS` é o flavor padrão. [TIP] ==== Isso pode ajudar a simplificar a lógica do [.filename]#Makefile# para também definir um `FLAVOR` como: [.programlisting] .... FLAVOR?= ${FLAVORS:[1]} .... ==== [IMPORTANT] ==== Para distinguir os flavors das opções, que são sempre letras maiúsculas, os nomes dos flavors podem conter _apenas_ letras minúsculas, números e underline `_`. ==== [[flavors-using-ex1]] .Uso Básico de Flavors [example] ==== Se um port tiver um port slave "lite", o port slave pode ser removido, e o port pode ser convertido em flavors com: [.programlisting] .... FLAVORS= default lite lite_PKGNAMESUFFIX= -lite [...] .if ${FLAVOR:U} != lite [enable non lite features] .endif .... [NOTE] ====== O primeiro flavor é o padrão, e é chamado aqui de `default`. Não é uma obrigação e, se possível, use um nome de flavor mais específico, como em <>. ====== ==== [[flavors-using-ex2]] .Outro Uso Básico de Flavors [example] ==== Se um port tiver um port slave `-nox11`, o port slave pode ser removido, e o port pode ser convertido em flavors com: [.programlisting] .... FLAVORS= x11 nox11 FLAVOR?= ${FLAVORS:[1]} nox11_PKGNAMESUFFIX= -nox11 [...] .if ${FLAVOR} == x11 [enable x11 features] .endif .... ==== [[flavors-using-ex3]] .Uso Mais Complexo de Flavors [example] ==== Aqui está um excerto ligeiramente editado do que está presente em package:devel/libpeas[], um port que usa os <>. Com as versões padrões do Python 2 e 3 sendo 2.7 e 3.6, ele irá automaticamente mudar para `FLAVORS=py27 py36` [.programlisting] .... USES= gnome python USE_PYTHON= flavors <.> .if ${FLAVOR:Upy27:Mpy2*} <.> USE_GNOME= pygobject3 <.> CONFIGURE_ARGS+= --enable-python2 --disable-python3 BUILD_WRKSRC= ${WRKSRC}/loaders/python <.> INSTALL_WRKSRC= ${WRKSRC}/loaders/python <.> .else # py3* USE_GNOME+= py3gobject3 <.> CONFIGURE_ARGS+= --disable-python2 --enable-python3 \ ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config <.> BUILD_WRKSRC= ${WRKSRC}/loaders/python3 <.> INSTALL_WRKSRC= ${WRKSRC}/loaders/python3 <.> .endif py34_PLIST= ${.CURDIR}/pkg-plist-py3 <.> py35_PLIST= ${.CURDIR}/pkg-plist-py3 <.> py36_PLIST= ${.CURDIR}/pkg-plist-py3 <.> .... <.> Este port não usa o `USE_PYTHON=distutils` mas precisa do flavor Python de qualquer maneira. <.> Para proteger contra o `FLAVOR` estar vazio, o que causaria um erro no man:make[1], use `${FLAVOR:U}` em comparações de strings em vez de `${FLAVOR}`. <.> As ligações gobject3 doGnome Python têm dois nomes diferentes, um para Python2, pygobject3 e um para Python3, py3gobject3. <.> O script `configure` tem que ser executado em [.filename]#${WRKSRC}#, mas estamos interessados ​​apenas em compilar e instalar as partes Python 2 ou Python 3 do software, então configure os diretórios base de compilação e instalação apropriadamente. <.> Sugestão sobre o nome correto do caminho do script de configuração do Python 3. <.> A lista de empacotamento é diferente quando compilada com Python 3. Como existem três possíveis versões do Python3 , defina `PLIST` para todos os três usando o <>. ==== [[flavors-using-helpers]] === Flavors Helpers Para tornar o [.filename]#Makefile# mais fácil de ser escrito, existem alguns flavors helpers. Esta lista de helpers definirá sua variável: * `flavor_PKGNAMEPREFIX` * `flavor_PKGNAMESUFFIX` * `flavor_PLIST` * `flavor_DESCR` Esta lista de helpers será anexada à sua variável: * `flavor_CONFLICTS` * `flavor_CONFLICTS_BUILD` * `flavor_CONFLICTS_INSTALL` * `flavor_PKG_DEPENDS` * `flavor_EXTRACT_DEPENDS` * `flavor_PATCH_DEPENDS` * `flavor_FETCH_DEPENDS` * `flavor_BUILD_DEPENDS` * `flavor_LIB_DEPENDS` * `flavor_RUN_DEPENDS` * `flavor_TEST_DEPENDS` [[flavors-helpers-ex1]] .Flavor Específico `PKGNAME` [example] ==== Como todos os pacotes devem ter um nome de pacote diferente, os flavors devem mudar os seus, usando `flavor_PKGNAMEPREFIX` e o `flavor_PKGNAMESUFFIX` torna isso fácil: [.programlisting] .... FLAVORS= normal lite lite_PKGNAMESUFFIX= -lite .... ==== [[flavors-auto-php]] == `USES=php` e Flavors Ao usar o <> com um destes argumentos, `phpize`, `ext`, `zend` ou `pecl`, o port terá automaticamente o `FLAVORS` preenchido com a versão PHP que ele suporta. [NOTE] ==== Todos os exemplos assumem que as versões PHP suportadas atualmente são 5.6, 7.0, 7.1 e 7.2. ==== [[flavors-auto-php-ex1]] .Extensão Simples `USES=php` [example] ==== Isso irá gerar o pacote para todas as versões suportadas: [.programlisting] .... PORTNAME= some-ext PORTVERSION= 0.0.1 PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} USES= php:ext .... Isto irá gerar pacotes para todas as versões suportadas, menos a 7.2: [.programlisting] .... PORTNAME= some-ext PORTVERSION= 0.0.1 PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} USES= php:ext IGNORE_WITH_PHP= 72 .... ==== [[flavors-auto-php-app]] === Flavors PHP com Aplicações PHP Aplicações PHP também podem ter flavors. Isso permite gerar pacotes para todas as versões do PHP, para que os usuários possam usá-los com qualquer versão que precisarem em seus servidores. [IMPORTANT] ==== Aplicações PHP que são acrescidas de flavors _devem_ acrescentar `PHP_PKGNAMESUFFIX` aos nomes dos pacotes. ==== [[flavors-auto-php-app-ex1]] .Adicionando Flavors em uma Aplicação PHP [example] ==== Incluir o suporte de Flavors em uma aplicação PHP é simples: [.programlisting] .... PKGNAMESUFFIX= ${PHP_PKGNAMESUFFIX} USES= php:flavors .... ==== [TIP] ==== Ao adicionar uma dependência em um port com flavors PHP, use `@${PHP_FLAVOR}`. _Nunca_ use `FLAVOR` diretamente. ==== [[flavors-auto-python]] == `USES=python` e Flavors Ao usar <> e `USE_PYTHON=distutils`, o port irá automaticamente preencher `FLAVORS` com a versão Python que suporta. [[flavors-auto-python-ex1]] .Simples `USES=python` [example] ==== Supondo que as versões suportadas do Python são 2.7, 3.4, 3.5 e 3.6, e a versão padrão do Python 2 e 3 são 2.7 e 3.6, um port com: [.programlisting] .... USES= python USE_PYTHON= distutils .... Receberá esses flavors: `py27` e `py36`. [.programlisting] .... USES= python USE_PYTHON= distutils allflavors .... Receberá esses flavors: `py27`, `py34`, `py35` e `py36`. ==== [[flavors-auto-python-ex2]] .`USES=python` com Requisitos de Versão [example] ==== Supondo que as versões suportadas do Python são 2.7, 3.4, 3.5 e 3.6, e a versão padrão do Python 2 e 3 são 2.7 e 3.6, um port com: [.programlisting] .... USES= python:-3.5 USE_PYTHON= distutils .... Vai ter esse flavor: `py27`. [.programlisting] .... USES= python:-3.5 USE_PYTHON= distutils allflavors .... Receberá esses flavors: `py27`, `py34` e `py35`. [.programlisting] .... USES= python:3.4+ USE_PYTHON= distutils .... Vai ter esse flavor: `py36`. [.programlisting] .... USES= python:3.4+ USE_PYTHON= distutils allflavors .... Receberá esses flavors: `py34`, `py35` e `py36`. ==== A variável `PY_FLAVOR` é disponibilizada para depender da versão correta dos módulos Python. Todas as dependências em ports Python com flavors devem usar `PY_FLAVOR`, e não `FLAVOR` diretamente. [[flavors-auto-python-ex3]] .Para um port que não usa `distutils` [example] ==== Se a versão padrão do Python3 é 3.6, o seguinte irá definir a variável `PY_FLAVOR` para `py36`: [.programlisting] .... RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}mutagen>0:audio/py-mutagen@${PY_FLAVOR} USES= python:3.5+ .... ==== [[flavors-auto-lua]] == `USES=lua` e Flavors -Ao usar <> ou <>, o port terá automaticamente `FLAVORS` preenchidos com as versões Lua que suporta. No entanto, não se espera que aplicativos comuns (em vez de módulos Lua) usem este recurso; a maioria das aplicações que incorporam ou usam Lua simplesmente devem usar `USES=lua`. +Ao usar crossref:uses[uses-lua,`lua:module`] ou crossref:uses[uses-lua,`lua:flavors`], o port terá automaticamente `FLAVORS` preenchidos com as versões Lua que suporta. No entanto, não se espera que aplicativos comuns (em vez de módulos Lua) usem este recurso; a maioria das aplicações que incorporam ou usam Lua simplesmente devem usar `USES=lua`. `LUA_FLAVOR` está disponível (e deve ser usado) para depender da versão correta das dependências, independentemente do port usar os parâmetros `flavors` ou `module`. -Veja <> para maiores informações. +Veja crossref:special[using-lua,Usando Lua] para maiores informações. diff --git a/documentation/content/pt-br/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/keeping-up/_index.adoc similarity index 100% rename from documentation/content/pt-br/books/porters-handbook/keeping-up/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/keeping-up/_index.adoc diff --git a/documentation/content/pt-br/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/makefiles/_index.adoc similarity index 98% rename from documentation/content/pt-br/books/porters-handbook/makefiles/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/makefiles/_index.adoc index 97d6a7a8d0..f3d616d4c2 100644 --- a/documentation/content/pt-br/books/porters-handbook/makefiles/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/makefiles/_index.adoc @@ -1,4809 +1,4809 @@ --- title: Capítulo 5. Configurando o Makefile prev: books/porters-handbook/slow-porting next: books/porters-handbook/special --- [[makefiles]] = Configurando o Makefile :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Configurar o [.filename]#Makefile# é bastante simples e, novamente, sugerimos examinar os exemplos existentes antes de começar. Além disso, há um <> neste manual, então dê uma olhada e por favor siga a ordem das variáveis ​​e seções naquele modelo para tornar o port mais fácil para os outros lerem. Considere estes problemas em sequência durante o projeto do novo [.filename]#Makefile#: [[makefile-source]] == O Código Fonte Original Ele está em `DISTDIR` como um tarball `gzip` e é chamado de algo como [.filename]#foozolix-1.2.tar.gz#? Se assim for, vá para o próximo passo. Caso contrário, o formato do arquivo de distribuição pode necessitar da substituição de uma ou mais das variáveis `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX` ou `DISTFILES`. Na pior das hipóteses, crie um target personalizado `do-extract` para substituir o padrão. Isso raramente é necessário. [[makefile-naming]] === Nomeando A primeira parte do [.filename]#Makefile# do port o nomeia, descreve seu número de versão e o lista na categoria correta. [[makefile-portname]] === `PORTNAME` Setar `PORTNAME` ao nome base do software. Isso é usado como base para o pacote do FreeBSD, e para o <>. [IMPORTANT] ==== O nome do pacote deve ser único em toda a árvore de ports. Certifique-se de que o `PORTNAME` já não está em uso por um port existente, e que nenhum outro port já tem o mesmo `PKGBASE`. Se o nome já tiver sido usado, adicione <>. ==== [[makefile-versions]] === Versões, `DISTVERSION` ou `PORTVERSION` Setar `DISTVERSION` para o número da versão do software. `PORTVERSION` é a versão usada para o pacote do FreeBSD. Será automaticamente derivado de `DISTVERSION` para ser compatível com o esquema de versionamento de pacotes do FreeBSD. Se a versão contiver _letras_, pode ser necessário definir `PORTVERSION` e não `DISTVERSION`. [IMPORTANT] ==== Não é possível utilizar `PORTVERSION` e `DISTVERSION` juntos, deve ser ser definido um de cada vez. ==== De tempos em tempos, alguns softwares usam um esquema de versão que não é compatível em como o `DISTVERSION` traduz a versão no `PORTVERSION`. [TIP] ==== Ao atualizar um port, é possível usar o man:pkg-version[8]`-t` para verificar se a nova versão é maior ou menor do que antes. Veja <>. ==== [[makefile-versions-ex-pkg-version]] .Usando man:pkg-version[8] para comparar versões. [example] ==== `pkg version -t` recebe duas versões como argumentos, responderá com `<`, `=` ou `>` se a primeira versão for menor, igual ou maior que a segunda versão, respectivamente. [source,shell] .... % pkg version -t 1.2 1.3 < <.> % pkg version -t 1.2 1.2 = <.> % pkg version -t 1.2 1.2.0 = <.> % pkg version -t 1.2 1.2.p1 > <.> % pkg version -t 1.2.a1 1.2.b1 < <.> % pkg version -t 1.2 1.2p1 < <.> .... <.> `1.2` é menor que `1.3`. <.> `1.2` e `1.2` são iguais, pois têm a mesma versão. <.> `1.2` e `1.2.0` são iguais, pois valor vazio é igual a zero. <.> `1.2` é maior que `1.2.p1` por causa do `.p1`, pense em "pre-release 1". <.> `1.2.a1` é menor que `1.2.b1`, pense em "alfa" e "beta" e `a` é menor que `b`. <.> `1.2` é menor que `1.2p1` por causa do `2p1`, pense em "2, nível de patch 1" que é uma versão depois de qualquer `2.X` mas antes de `3`. [NOTE] ====== Aqui, `a`, `b` e `p` são usados ​​como se significassem "alfa", "beta" ou "pre-release" e "nível de patch", mas elas são apenas letras e são classificados por ordem alfabética, portanto, qualquer letra pode ser utilizada, e elas serão ordenadas de forma adequada. ====== ==== .Exemplos de `DISTVERSION` e de Derivações `PORTVERSION` [cols="1,1", frame="none", options="header"] |=== | DISTVERSION | PORTVERSION |0.7.1d |0.7.1.d |10Alpha3 |10.a3 |3Beta7-pre2 |3.b7.p2 |8:f_17 |8f.17 |=== [[makefile-versions-ex1]] .Usando `DISTVERSION` [example] ==== Quando a versão contém apenas números separados por pontos, traços ou sublinhados, use `DISTVERSION`. [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-4 .... Isso irá gerar um `PORTVERSION 1.2.4`. ==== [[makefile-versions-ex2]] .Usando `DISTVERSION` Quando a Versão Começa com uma Letra ou um Prefixo [example] ==== Quando a versão começa ou termina com uma letra, um prefixo ou um sufixo que não faz parte da versão, use `DISTVERSIONPREFIX`, `DISTVERSION` e `DISTVERSIONSUFFIX`. Se a versão for `v1.2-4`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= v DISTVERSION= 1_2_4 .... Algumas vezes, projetos usando GitHub usará seu nome em suas versões. Por exemplo, a versão pode ser `nekoto-1.2-4`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= nekoto- DISTVERSION= 1.2_4 .... Esses projetos também usam algumas strings no final da versão, por exemplo,`1.2-4_RELEASE`: [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-4 DISTVERSIONSUFFIX= _RELEASE .... Ou eles fazem ambos, por exemplo,`nekoto-1.2-4_RELEASE`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= nekoto- DISTVERSION= 1.2-4 DISTVERSIONSUFFIX= _RELEASE .... `DISTVERSIONPREFIX` e `DISTVERSIONSUFFIX` não serão usados durante a construção do `PORTVERSION`, mas usado apenas em `DISTNAME`. Todos exemplos irão gerar um `PORTVERSION` com valor `1.2.4`. ==== [[makefile-versions-ex3]] .Usando `DISTVERSION` Quando a Versão Contém Letras Significando "alpha", "beta" ou "pre-release" [example] ==== Quando a versão contém números separados por pontos, traços ou underlines, e letras são usadas para significar "alpha", "beta" ou "pre-release", no sentido de que vem antes das versões sem letras, use `DISTVERSION`. [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-pre4 .... [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2p4 .... Ambos irão gerar um `PORTVERSION` com valor `1.2.p4` que é menor do que 1.2. man:pkg-version[8] pode ser usado para verificar esse fato: [source,shell] .... % pkg version -t 1.2.p4 1.2 < .... ==== [[makefile-versions-ex4]] .Não use `DISTVERSION` Quando a Versão Contém Letras que Significam "Nível de Patch" [example] ==== Quando a versão contém letras que não significam "alpha", "beta" ou "pre", e estão mais para um "nível de patch", no sentido de que vem depois da versão sem as letras, use `PORTVERSION`. [.programlisting] .... PORTNAME= nekoto PORTVERSION= 1.2p4 .... Neste caso, usar `DISTVERSION` não é possível porque geraria uma versão `1.2.p4` o que seria menor que `1.2` e não maior.man:pkg-version[8] irá constatar isso: [source,shell] .... % pkg version -t 1.2 1.2.p4 > <.> % pkg version -t 1.2 1.2p4 < <.> .... <.> `1.2` é maior que `1.2.p4`, o que é _errado_ nesse caso. <.> `1.2` é menor que `1.2p4`, que é o que era necessário. ==== Para alguns exemplos mais avançados de configuração do `PORTVERSION`, quando a versão do software não é realmente compatível com o FreeBSD, ou `DISTNAME` quando o arquivo de distribuição não contém a versão em si, consulte <>. [[makefile-naming-revepoch]] === `PORTREVISION` e `PORTEPOCH` [[makefile-portrevision]] ==== `PORTREVISION` `PORTREVISION` é um valor monotonicamente crescente que é redefinido para 0 com cada incremento de `DISTVERSION`, normalmente toda vez que houver uma nova versão oficial do fornecedor. E se `PORTREVISION` é diferente de zero, o valor é anexado ao nome do pacote. Mudanças em `PORTREVISION` são usadas ​​por ferramentas automatizadas como man:pkg-version[8] para determinar se um novo pacote está disponível. `PORTREVISION` deve ser incrementado toda vez que uma alteração for feita no port onde se altera o pacote gerado de alguma forma. Isso inclui alterações que afetam apenas um pacote compilado com <> não padrão. Exemplos de quando `PORTREVISION` deve ser alterado: * Adição de correções para corrigir vulnerabilidades de segurança, bugs ou para adicionar novas funcionalidades ao port. * Alterações no [.filename]#Makefile# do port para ativar ou desativar as opções de tempo de compilação no pacote. * Alterações na lista de empacotamento ou no comportamento de tempo de instalação do pacote. Por exemplo, uma alteração em um script que gera dados iniciais para o pacote, como chaves de host man:ssh[1]. * Bump de versão da dependência de biblioteca compartilhada de um port (nesse caso, alguém tentando instalar o pacote antigo depois de instalar uma versão mais nova da dependência falhará, pois procurará a libfoo.x antiga em vez da libfoo.(x+1)). * Mudanças silenciosas no distfile do port que possuem diferenças funcionais significativas. Por exemplo, mudanças no distfile que requerem uma correção para [.filename]#distinfo# sem alteração correspondente para `DISTVERSION`, onde um `diff -ru` das versões antiga e nova mostra mudanças não triviais no código. Exemplos de alterações que não requerem uma alteração no `PORTREVISION`: * Mudanças de estilo no esqueleto do port sem alteração funcional ao que aparece no pacote resultante. * Mudanças para `MASTER_SITES` ou outras alterações funcionais no port que não afetem o pacote resultante. * Patches triviais para o distfile, como correção de erros de digitação, que não são importantes o suficiente para que os usuários do pacote tenham que se dar ao trabalho de atualizar. * Correções de compilação que fazem com que um pacote se torne compilável onde antes estava falhando. Desde que as alterações não introduzam nenhuma mudança funcional em nenhuma outra plataforma na qual o port tenha sido compilado anteriormente. `PORTREVISION` reflete o conteúdo do pacote, se o pacote não foi compilado anteriormente, então não há necessidade de incrementar o `PORTREVISION` para registrar uma mudança. Uma regra geral é decidir se a mudança em um port é algo que _algumas_ pessoas se beneficiariam em ter. Por causa de um aprimoramento, conserto ou em virtude de que o novo pacote funcione de fato. Em seguida, pondere que, de fato, isso fará com que todos que regularmente atualizam sua árvore de ports sejam obrigados a atualiza-lo. Se sim, `PORTREVISION` deve ser incrementado. [NOTE] ==== Pessoas usando pacotes binários _nunca_ verão a atualização se `PORTREVISION` não for incrementado. Sem incrementar `PORTREVISION`, os package builders não têm como detectar a alteração e, portanto, não irão recompilar o pacote. ==== [[makefile-portepoch]] ==== `PORTEPOCH` De tempos em tempos, um fornecedor de software ou um mantenedor de port do FreeBSD fazem algo tolo e lançam uma versão de seu software que é numericamente menor que a versão anterior. Um exemplo disso é um port que vai de foo-20000801 para foo-1.0 ( o primeiro será incorretamente tratado como uma versão mais nova, já que 20000801 é um valor numericamente maior que 1). [TIP] ==== Os resultados das comparações de números de versão nem sempre são óbvios. `pkg version` (veja man:pkg-version[8]) pode ser usado para testar a comparação de duas sequências de números de versão. Por exemplo: [source,shell] .... % pkg version -t 0.031 0.29 > .... A saida `>` indica que a versão 0.031 é considerada maior que a versão 0.29, o que pode não ter sido óbvio para o mantenedor do port. ==== Em situações como essa, `PORTEPOCH` deve ser incrementado. E se `PORTEPOCH` é diferente de zero, ele é anexado ao nome do pacote conforme descrito na seção 0 acima. `PORTEPOCH` nunca deve ser diminuído ou redefinido para zero, porque isso faria com que a comparação com um pacote de uma época anterior falhasse. Por exemplo, o pacote não seria detectado como desatualizado. O novo número da versão, `1.0.1` no exemplo acima, ainda é numericamente menor que a versão anterior, 20000801, mas o sufixo `1` é tratado especialmente por ferramentas automatizadas e considerado maior que o sufixo `0` implícito no pacote anterior. Remover ou resetar o `PORTEPOCH` incorretamente conduz ao luto eterno. Se a discussão acima não foi clara o suficiente, por favor consulte a http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[ Lista de discussão de ports do FreeBSD]. É esperado que `PORTEPOCH` não seja utilizado na maioria dos ports, e que seja feito o uso sensato do `DISTVERSION`, ou que o `PORTVERSION` seja usado com cuidado também, isso muitas vezes pode evitar que uma versão futura do software altere a estrutura da versão. No entanto, é necessário que os porters do FreeBSD tenham cuidado quando uma versão do fornecedor é feita sem um número de versão oficial - como um código de release "snapshot". A tentação é rotular a release com a data de lançamento, o que causará problemas como no exemplo acima, quando um novo release "oficial" é feito. Por exemplo, se um snapshot de release é feito na data `20000917` e a versão anterior do software era a versão `1.2`, não use `20000917` no `DISTVERSION`. A maneira correta é um `DISTVERSION` com valor `1.2.20000917`, ou similar, para que a próxima versão, digamos `1.3`, ainda seja um valor numericamente maior. [[makefile-portrevision-example]] ==== Exemplo de Uso `PORTREVISION` e `PORTEPOCH` O port `gtkmumble`, versão `0.10` está comitado na coleção de ports: [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.10 .... `PKGNAME` torna-se `gtkmumble-0.10`. Uma falha de segurança é descoberta, o que requer um patch local do FreeBSD. `PORTREVISION` é alterado de acordo. [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.10 PORTREVISION= 1 .... `PKGNAME` torna-se `gtkmumble-0.10_1` Uma nova versão é lançada pelo fornecedor, numerada como `0.2` (acontece que o autor realmente pretendia que `0.10` significa-se realmente `0.1.0`, não "o que vem depois de 0.9" - oops, tarde demais agora). Como a nova versão secundária `2` é numericamente menor que a versão anterior `10`, `PORTEPOCH` deve ser incrementado para forçar manualmente que o novo pacote seja detectado como "mais recente". Como é uma nova versão do fornecedor, `PORTREVISION` é redefinido para 0 (ou removido do [.filename]#Makefile#). [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.2 PORTEPOCH= 1 .... `PKGNAME` torna-se `gtkmumble-0.2,1` O próximo lançamento é 0.3. Desde que `PORTEPOCH` nunca diminua, as variáveis ​​de versão são agora: [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.3 PORTEPOCH= 1 .... `PKGNAME` torna-se `gtkmumble-0.3,1` [NOTE] ==== E se `PORTEPOCH` for redefinido para `0` com esta atualização, alguém que instalou o `gtkmumble-0.10_1` não detectaria o `gtkmumble-0.3` como pacote mais novo, desde que `3` ainda é numericamente menor que `10`. Lembre-se, este é o ponto principal de `PORTEPOCH` em primeiro lugar. ==== [[porting-pkgnameprefix-suffix]] === `PKGNAMEPREFIX` e `PKGNAMESUFFIX` Duas variáveis ​​opcionais, `PKGNAMEPREFIX` e `PKGNAMESUFFIX`, são combinadas com `PORTNAME` e `PORTVERSION` para formar `PKGNAME` como `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Certifique-se de que isto está de acordo com as nossas <>. Em particular, o uso de um hífen (`-`) dentro de `PORTVERSION` _não é_ permitido. Além disso, se o nome do pacote tiver o _language-_ ou a parte _-compiled.specifics_ (veja abaixo), use `PKGNAMEPREFIX` e `PKGNAMESUFFIX`, respectivamente. Não os faça parte de `PORTNAME`. [[porting-pkgname]] === Convenções de Nomenclatura de Pacotes Estas são as convenções a serem seguidas ao nomear pacotes. Isso é para facilitar a varredura do diretório de pacotes, já que existem milhares de pacotes e os usuários irão pegar ranço se eles machucarem seus olhos! Nomes de pacotes tomam a forma de [.filename]#language_region-name-compiled.specifics-version.numbers#. O nome do pacote é definido como `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Certifique-se de definir as variáveis ​​para estar em conformidade com esse formato. [[porting-pkgname-language]] [.filename]#language_region-#:: O FreeBSD se esforça para suportar a linguagem nativa de seus usuários. A parte _language-_ é uma abreviação de duas letras da linguagem natural definida pela ISO-639 quando o port é específico para um determinado idioma. Exemplos são `ja` para japonês, `ru` para russo,`vi` para vietnamita, `zh` para o chinês, `ko` para coreano e `de` para alemão. + Se o port for específico de uma determinada região dentro da área de idioma, adicione também o código do país de duas letras. Exemplos são `en_US` para Inglês dos EUA e `fr_CH` para o Francês Suíço. + A parte _language-_ é definida em `PKGNAMEPREFIX`. [[porting-pkgname-name]] [.filename]#name#:: Certifique-se de que o nome e a versão do port estejam claramente separados e colocados em `PORTNAME` e `DISTVERSION`. A única razão para `PORTNAME` conter uma parte da versão é se a distribuição upstream é realmente chamada dessa forma, como no package:textproc/libxml2[] ou package:japanese/kinput2-freewnn[]. De outra forma, `PORTNAME` não pode conter informações específicas da versão. É normal que vários ports tenham o mesmo `PORTNAME`, como os ports package:www/apache*[] fazem; Nesse caso, versões diferentes (e entradas de índice diferentes) são distinguidas por valores `PKGNAMEPREFIX` e `PKGNAMESUFFIX`. + Há uma tradição de nomear módulos `Perl 5` com sufixo `p5-` e convertendo o separador de dois pontos para um hífen. Por exemplo, o modulo `Data::Dumper` torna-se `p5-Data-Dumper`. [[porting-pkgname-compiled-specifics]] [.filename]#-compiled.specifics#:: Se o port pode ser construído com diferentes <> (geralmente parte do nome do diretório em uma família de ports), a parte _-compiled.specifics_ indica os padrões compilados. O hífen é opcional. Exemplos são tamanho de papel e unidades de fonte. + A parte _-compiled.specifics_ é definida em `PKGNAMESUFFIX`. [[porting-pkgname-version-numbers]] [.filename]#-version.numbers#:: A string da versão segue um hífen (`-`) e é uma lista separada por pontos de números inteiros e letras minúsculas. Em particular, não é permitido ter outro hífen dentro da string de versão. A única exceção é a string `pl` (significando "patchlevel"), que pode ser usado _apenas_ quando não há números de versão maiores e menores no software. Se a versão do software tiver sequências como "alpha", "beta", "rc" ou "pre", use a primeira letra e coloque imediatamente após um ponto. Se a sequência da versão continuar após esses nomes, os números seguirão o alfabeto simples sem um ponto extra entre eles (por exemplo,`1.0b2`). + A ideia é facilitar a classificação dos ports observando a string de versão. Em particular, certifique-se de que os componentes do número da versão estejam sempre delimitados por um ponto e, se a data fizer parte da string, use o formato `dyyyy.mm.dd`, não `dd.mm.yyyy` ou o não compatível com o formato Y2K `yy.mm.dd`. É importante prefixar a versão com uma letra, aqui `d` (para data), no caso de uma versão com um número de versão real, que seria numericamente inferior a `_yyyy_`. [IMPORTANT] ==== O nome do pacote deve ser único entre todos os ports, verifique se ainda não existe um port com o mesmo `PORTNAME` e se houver, adicione um dos <>. ==== Aqui estão alguns exemplos (reais) de como converter o nome como chamado pelos autores do software para um nome de pacote adequado, para cada linha, apenas um dos `DISTVERSION` ou `PORTVERSION` está definido, dependendo de qual seria usado no [.filename]#Makefile#: .Exemplos de Nomes de Pacotes [cols="1,1,1,1,1,1,1", frame="none", options="header"] |=== | Nome da Distribuição | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | DISTVERSION | PORTVERSION | Razão ou comentário |mule-2.2.2 |(vazio) |mule |(vazio) |2.2.2 | |Nenhuma alteração é necessária |mule-1.0.1 |(vazio) |mule |1 |1.0.1 | |Esta é a versão 1 do mule e a versão 2 já existe |EmiClock-1.0.2 |(vazio) |emiclock |(vazio) |1.0.2 | |Sem nomes em maiúsculas para programas individuais |rdist-1.3alpha |(vazio) |rdist |(vazio) |1.3alfa | |Versão será `1.3.a` |es-0.9-beta1 |(vazio) |es |(vazio) |0.9-beta1 | |Versão será `0.9.b1` |mailman-2.0rc3 |(vazio) |mailman |(vazio) |2.0rc3 | |Versão será `2.0.r3` |v3.3beta021.src |(vazio) |tiff |(vazio) | |3.3 |O que diabos foi isso afinal? |tvtwm |(vazio) |tvtwm |(vazio) | |p11 |Nenhuma versão no nome do arquivo, use o que o upstream diz que é |piewm |(vazio) |piewm |(vazio) |1.0 | |Nenhuma versão no nome do arquivo, use o que o upstream diz que é |xvgr-2.10pl1 |(vazio) |xvgr |(vazio) | |2.10.pl1 |Nesse caso,`pl1` significa nível de patch, então usar DISTVERSION não é possível. |gawk-2.15.6 |ja- |gawk |(vazio) |2.15.6 | |Versão em japonês |psutils-1.13 |(vazio) |psutils |-letter |1.13 | |Tamanho do papel codificado no tempo de compilação do pacote |pkfonts |(vazio) |pkfonts |300 |1.0 | |Pacote para fontes de 300dpi |=== Se não houver absolutamente nenhum rastro de informações de versão co código fonte original e é improvável que o autor original vá liberar outra versão, basta definir a string de versão para `1.0` (como o exemplo `piewm` acima). Caso contrário, pergunte ao autor original ou use a string de data com valor de quando a código fonte foi lançado como (`dyyyy.mm.dd` ou `dyyyymmdd`) como a versão. [TIP] ==== Use qualquer letra. Aqui,`d` significa data, se o código for um repositório do Git, `g` seguido pela data de commit é normalmente utilizado, `s` para snapshot também é comum. ==== [[makefile-categories]] == Categorização [[makefile-categories-definition]] === `CATEGORIES` Quando um pacote é criado, ele é colocado em [.filename]#/usr/ports/packages/All# e links são feitos de um ou mais subdiretórios de [.filename]#/usr/ports/packages#. Os nomes desses subdiretórios são especificados pela variável `CATEGORIES`. O objetivo é facilitar a vida do usuário quando ele estiver vasculhando a pilha de pacotes no site FTP ou no CD-ROM. Por favor, dê uma olhada na <> e escolha as que são adequadas para o port. Esta lista também determina de onde, na árvore de ports, o port será importado. Se houver mais de uma categoria aqui, os arquivos do port devem ser colocados no subdiretório com o nome da primeira categoria. Veja <> para mais informação sobre como escolher as categorias certas. [[porting-categories]] === Lista Atual de Categorias Aqui está a lista atual de categorias de ports. As marcadas com um asterisco (`*`) são categorias _virtuais_ - aquelas que não possuem um subdiretório correspondente na árvore de ports. Elas são usadas ​​apenas como categorias secundárias e apenas para fins de pesquisa. [NOTE] ==== Para categorias não virtuais, há uma descrição de uma linha em `COMMENT` no [.filename]#Makefile# desse subdiretório. ==== [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Categoria | Descrição | Notas |[.filename]#accessibility# |Ports para ajudar usuários com deficiências. | |[.filename]#afterstep# `*` |Ports para apoiar o gerenciador de janelas http://www.afterstep.org[AfterStep]. | |[.filename]#arabic# |Suporte ao idioma árabe". | |[.filename]#archivers# |Ferramentas de arquivamento. | |[.filename]#astro# |Ports astronômicos. | |[.filename]#audio# |Suporte de som. | |[.filename]#benchmarks# |Utilitários de benchmarking. | |[.filename]#biology# |Software relacionado à biologia. | |[.filename]#cad# |Ferramentas de desenho assistidas por computador. | |[.filename]#chinese# |Suporte ao idioma chinês. | |[.filename]#comms# |Software de comunicação. |Principalmente software para falar com o port serial. |[.filename]#converters# |Conversores de código de caracteres. | |[.filename]#databases# |Bancos de dados. | |[.filename]#deskutils# |Coisas que costumavam estar na área de trabalho antes dos computadores serem inventados. | |[.filename]#devel# |Utilitários de desenvolvimento. |Não coloque bibliotecas aqui só porque são bibliotecas. Elas _não deveriam_ estar nesta categoria, a menos que elas realmente não pertençam a nenhum outro lugar. |[.filename]#dns# |Software relacionado ao DNS. | |[.filename]#docs# `*` |Meta-ports para documentação do FreeBSD. | |[.filename]#editors# |Editores gerais. |Editores especializados entram na seção para essas ferramentas. Por exemplo, um editor de fórmula matemática [.filename]#math#, e tem [.filename]#editores# como uma segunda categoria. |[.filename]#elisp# `*` |Emacs-lisp ports. | |[.filename]#emulators# |Emuladores para outros sistemas operacionais. |Emuladores de terminal _não_ estão aqui. Os baseados em X vão para o [.filename]#x11# e baseados em texto para qualquer [.filename]#comms# ou [.filename]#misc#, dependendo da funcionalidade exata. |[.filename]#enlightenment# `*` |Ports relacionados com o gerenciador de janelas Enlightenment. | |[.filename]#finance# |Aplicações monetárias, financeiras e relacionadas. | |[.filename]#french# |Suporte ao idioma francês. | |[.filename]#ftp# |Utilitários de cliente e servidor deFTP. |Se o port fala com FTP e HTTP, coloque-o em [.filename]#ftp# com uma categoria secundária de [.filename]#www#. |[.filename]#games# |Jogos. | |[.filename]#geography# `*` |Software relacionado à geografia. | |[.filename]#german# |Suporte ao idioma alemão. | |[.filename]#gnome# `*` |Ports do Projeto http://www.gnome.org[GNOME]. | |[.filename]#gnustep# `*` |Software relacionado ao ambiente de desktop GNUstep. | |[.filename]#graphics# |Utilitários gráficos. | |[.filename]#hamradio# `*` |Software para rádio amador. | |[.filename]#haskell# `*` |Software relacionado à linguagem Haskell. | |[.filename]#hebrew# |Suporte ao idioma hebraico. | |[.filename]#hungarian# |Suporte de idioma húngaro. | |[.filename]#irc# |Utilitários do Internet Relay Chat. | |[.filename]#japanese# |Suporte ao idioma japonês. | |[.filename]#java# |Software relacionado à linguagem Java(TM). |A categoria [.filename]#Java# não deve ser única para um port. Salvo para ports diretamente relacionadas à linguagem Java, os mantenedores de ports também são encorajados a não usar [.filename]#Java# como a principal categoria de um port. |[.filename]#kde# `*` |Ports do Projeto http://www.kde.org[KDE] (genérico). | |[.filename]#kde-applications# `*` |Aplicações do Projeto http://www.kde.org[KDE]. | |[.filename]#kde-frameworks# `*` |Bibliotecas add-on do Projeto http://www.kde.org[KDE] para programação com Qt. | |[.filename]#kde-plasma# `*` |Desktop do Projeto http://www.kde.org[KDE]. | |[.filename]#kld# `*` |Módulos carregáveis ​​do kernel. | |[.filename]#korean# |Suporte ao idioma coreano. | |[.filename]#lang# |Linguagens de programação. | |[.filename]#linux# `*` |Aplicações Linux e utilitários de suporte. | |[.filename]#lisp# `*` |Software relacionado à linguagem Lisp. | |[.filename]#mail# |Mail software. | |[.filename]#mate# `*` |Ports relacionado ao ambiente de desktop MATE, um fork do GNOME 2. | |[.filename]#math# |Software de computação numérica e outras utilidades para matemática. | |[.filename]#mbone# `*` |Aplicações MBone. | |[.filename]#misc# |Utilitários diversos |Coisas que não pertencem em nenhum outro lugar. Se possível, tente encontrar uma categoria melhor para o port do que `misc`, como os ports tendem a ser negligenciados aqui. |[.filename]#multimedia# |Software multimídia. | |[.filename]#net# |Software de rede diversos. | |[.filename]#net-im# |Software de mensagens instantâneas. | |[.filename]#net-mgmt# |Software de gerenciamento de rede. | |[.filename]#net-p2p# |Aplicativos de rede peer to peer. | |[.filename]#net-vpn# `*` |Aplicativos de Rede Privada Virtual. | |[.filename]#news# |Software de notícias USENET. | |[.filename]#parallel# `*` |Aplicativos que lidam com o paralelismo na computação. | |[.filename]#pear# `*` |Ports relacionados ao framework PHP Pear. | |[.filename]#perl5# `*` |Ports que exigem Perl versão 5 para rodar. | |[.filename]#plan9# `*` |Vários programas de http://www.cs.bell-labs.com/plan9dist/[Plan9]. | |[.filename]#polish# |Suporte ao idioma polonês". | |[.filename]#ports-mgmt# |Ports para gerenciar, instalar e desenvolver ports e pacotes do FreeBSD. | |[.filename]#portuguese# |Suporte ao idioma Português. | |[.filename]#print# |Software de Impressão. |As ferramentas de editoração eletrônica (pré-visualizadores etc.) também pertencem aqui. |[.filename]#python# `*` |Software relacionado a linguagem http://www.python.org/[Python]. | |[.filename]#ruby# `*` |Software relacionado a linguagem http://www.ruby-lang.org/[Ruby]. | |[.filename]#rubygems# `*` |Ports de pacotes http://www.rubygems.org/[RubyGems]. | |[.filename]#russian# |Suporte de idioma russo. | |[.filename]#scheme# `*` |Software relacionado à linguagem Scheme. | |[.filename]#science# |Ports científicos que não se encaixam em outras categorias, como [.filename]#astro#, [.filename]#biologia# e [.filename]#matemática#. | |[.filename]#security# |Utilitários de segurança. | |[.filename]#shells# |Linha de comando do shell. | |[.filename]#spanish# `*` |Suporte ao idioma espanhol. | |[.filename]#sysutils# |Utilidades do sistema. | |[.filename]#tcl# `*` |Ports que usam o Tcl para rodar. | |[.filename]#textproc# |Utilitários de processamento de texto. |Não inclui ferramentas de editoração eletrônica, que vão para [.filename]#print#. |[.filename]#tk# `*` |Ports que usam o Tk para rodar. | |[.filename]#ukrainian# |Suporte de idioma Ucraniano. | |[.filename]#vietnamese# |Suporte de idioma Vietnamita. | |[.filename]#wayland# `*` |Ports para suportar o servidor de display Wayland. | |[.filename]#windowmaker# `*` |Ports para suportar o gerenciador de janelas do WindowMaker. | |[.filename]#www# |Software relacionado à World Wide Web. |O suporte ao idioma HTML também pertence aqui. |[.filename]#x11# |O X Window System e seus amigos. |Esta categoria é apenas para software que suporta diretamente o sistema de janelas. Não coloque aplicativos regulares do X aqui. A maioria deles é usada em outras categorias [.filename]#x11- *# (veja abaixo). |[.filename]#x11-clocks# |X11 relógios. | |[.filename]#x11-drivers# |Drivers X11. | |[.filename]#x11-fm# |Gerentes de arquivos X11. | |[.filename]#x11-fonts# |Fontes X11 e utilitários de fonte. | |[.filename]#x11-servers# |Servidores X11. | |[.filename]#x11-themes# |X11 temas. | |[.filename]#x11-toolkits# |Kits de ferramentas X11. | |[.filename]#x11-wm# |Gerentes de janela do X11. | |[.filename]#xfce# `*` |Ports relacionados com o ambiente de trabalho http://www.xfce.org/[Xfce]. | |[.filename]#zope# `*` |http://www.zope.org/[Zope] suporte. | |=== [[choosing-categories]] === Escolhendo a Categoria Correta Como muitas das categorias se sobrepõem, escolher qual das categorias será a principal categoria do port pode ser entediante. Existem várias regras que governam essa questão. Aqui está a lista de prioridades, em ordem decrescente de precedência: * A primeira categoria deve ser uma categoria física (veja <>). Isso é necessário para o empacotamento funcionar. Categorias virtuais e categorias físicas podem ser misturadas depois disso. * As categorias específicas de idioma sempre vêm em primeiro lugar. Por exemplo, se o port instalar fontes X11 em japonês, a linha `CATEGORIES` deve ser [.filename]#japanese x11-fonts#. * Categorias específicas são listadas antes de outras menos específicas. Por exemplo, um editor de HTML é listado como [.filename]#www editors#, e não ao contrário. Além disso, não insira [.filename]#net# quando o port pertencer a qualquer uma das categorias [.filename]#irc#, [.filename]#mail#, [.filename]#news#, [.filename]#security# ou [.filename]#www#, pois [.filename]#net# está incluída implicitamente. * [.filename]#x11# é usado como uma categoria secundária somente quando a categoria principal é uma linguagem natural. Em particular, não coloque [.filename]#x11# na linha de categoria em aplicações X. * Os modes Emacs são colocados na mesma categoria de ports que a aplicação suportada pelo mode, e não em [.filename]#editors#. Por exemplo, um mode Emacs para editar código fonte de alguma linguagem de programação entra em [.filename]#lang#. * Ports que instalam módulos do kernel carregáveis ​​também têm a categoria virtual [.filename]#kld# na sua linha `CATEGORIES`. Esta é uma das coisas tratadas automaticamente adicionando `USES=kmod`. * [.filename]#misc# não aparece com nenhuma outra categoria não virtual. Se houver `misc` com outra categoria na linha `CATEGORIES`, isso significa que `misc` pode ser seguramente excluído e o port colocado apenas no outro subdiretório. * Se o port realmente não pertencer em nenhum outro lugar, coloque-o em [.filename]#misc#. Se a categoria não estiver claramente definida, por favor, insira um comentário sobre isso na submissão https://bugs.freebsd.org/submit/[do port] no banco de dados de bugs, para que possamos discuti-lo antes de importá-lo. Como committer, envie uma mensagem para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[lista de discussão de ports do FreeBSD], para podermos discutir isso primeiro. Com muita frequência, novos ports são importados na categoria errada, e depois são movidos imediatamente para a categoria correta. [[proposing-categories]] === Propondo uma Nova Categoria Como a Coleção de Ports vem crescendo com o tempo, várias novas categorias também são adicionadas. Novas categorias podem ser categorias _virtuais_- aquelas que não possuem um subdiretório correspondente na árvore de ports - ou _físicas_ - aquelas que possuem. Esta seção discute os problemas envolvidos na criação de uma nova categoria física. Leia atentamente antes de propor uma nova. Nossa prática atual tem sido a de evitar a criação de uma nova categoria física, a menos que um grande número de ports logicamente pertençam a ela, ou os ports que pertenceriam a ela sejam um grupo logicamente distinto de interesse geral limitado (por exemplo, categorias relacionadas com as línguas humanas faladas), ou de preferência ambas. A razão para isto é que tal mudança cria uma extref:{committers-guide}[quantidade grande de trabalho, ports] tanto para os committers quanto para todos os usuários que rastreiam alterações na coleção de ports. Além disso, propostas de alteração de categorias parecem naturalmente atrair controvérsias. (Talvez isso seja porque não há um consenso claro sobre quando uma categoria é "grande o suficiente", nem quando as categorias devem ser apenas para propósitos de busca (e, portanto, qual número de categorias seria um número ideal), e assim por diante.) Aqui está o procedimento: [.procedure] ==== . Proponha a nova categoria na http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[lista de discussão de ports do FreeBSD]. Inclua uma justificativa detalhada para a nova categoria, incluindo por que as categorias existentes não são suficientes, e a lista de ports existentes propostos para a mudança. (Se houver novos ports pendentes no Bugzilla que caberia nessa categoria, liste-os também.) Se você for o mantenedor e/ou o apresentador, respectivamente, mencione isso, pois isso pode ajudar no caso. . Participe da discussão. . Se parecer que há apoio o suficiente para a ideia, registre um PR que inclua a lógica e a lista de ports existentes que precisam ser movidos. O ideal é que este PR também inclua essas alterações: ** [.filename]##Makefile##s para os novos ports, uma vez que sejam recopiados ** [.filename]#Makefile# para a nova categoria ** [.filename]#Makefile# para as categorias dos ports antigos ** [.filename]##Makefile##s para ports que dependem dos ports antigos ** (para crédito extra, inclua os outros arquivos que precisam ser alterados, conforme o procedimento no Guia do Committer.) . Como isso afeta a infraestrutura do ports e envolve a movimentação e alteração de vários ports, pode ser necessário executar testes de regressão no cluster de build, e portanto, atribua o PR para a Equipe de Gerenciamento de Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org]. . Se esse PR for aprovado, um committer precisará seguir o restante do procedimento que é extref:{committers-guide}[descrito no Guia do Committer, ports]. ==== A proposta de uma nova categoria virtual é semelhante à acima, mas muito menos trabalhoso, já que nenhum port terá que ser movido. Nesse caso, os únicos patches a serem incluídos no PR serão aqueles para adicionar a nova categoria na linha `CATEGORIES` dos ports afetados. [[proposing-reorg]] === Propondo Reorganizar Todas as Categorias Ocasionalmente alguém propõe reorganizar as categorias com uma estrutura de dois níveis, ou algum outro tipo de estrutura de palavras-chave. Até o momento, nada vem de nenhuma dessas propostas porque, embora sejam muito fáceis de fazer, o esforço envolvido com qualquer readequação de toda a coleção de ports existente é assustadora, para se dizer o mínimo. Por favor, leia o histórico dessas propostas nos arquivos da lista de discussão antes de postar essa idéia. Além disso, esteja preparado para ser desafiado a oferecer um protótipo funcional. [[makefile-distfiles]] == Os Arquivos de Distribuição A segunda parte do [.filename]#Makefile# descreve os arquivos que devem ser baixados para compilar o port e onde eles podem ser baixados. [[makefile-distname]] === `DISTNAME` `DISTNAME` é o nome do port, conforme chamado pelos autores do software. `DISTNAME` é derivado de `${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}`, e se não estiver definido, `DISTVERSION` é derivado de `${PORTVERSION}`, portanto altere `DISTNAME` somente se necessário. `DISTNAME` é usado apenas em dois lugares. Primeiro, na lista de arquivos de distribuição (`DISTFILES`) padrão para `${DISTNAME} ${EXTRACT_SUFX}`. Em segundo lugar, espera-se que o arquivo de distribuição seja extraído em um subdiretório denominado `WRKSRC`, cujo padrão é [.filename]#work/${DISTNAME}#. Alguns nomes de distribuição de fornecedores que não se encaixam no `${PORTNAME}-${PORTVERSION}`-scheme podem ser tratados automaticamente configurando `DISTVERSIONPREFIX`, `DISTVERSION` e `DISTVERSIONSUFFIX`. `PORTVERSION` será derivado de `DISTVERSION` automaticamente. [IMPORTANT] ==== Apenas um dos `PORTVERSION` e `DISTVERSION` pode ser definido de cada vez. E se `DISTVERSION` não derivar um `PORTVERSION` correto, não use `DISTVERSION`. ==== Se o esquema de versão upstream puder ser derivado em um esquema de versão compatível com o ports, defina uma variável para a versão upstream, _não_ use `DISTVERSION` como o nome da variável. Defina `PORTVERSION` para a versão computada com base na variável criada, e defina `DISTNAME` adequadamente. Se o esquema de versão upstream não puder ser facilmente configurado para um valor compatível com o ports, defina `PORTVERSION` para um valor sensato, e defina `DISTNAME` com `PORTNAME` com a versão literal do upstream. [[makefile-distname-ex1]] .Derivando `PORTVERSION` Manualmente [example] ==== BIND9 usa um esquema de versão que não é compatível com as versões de ports (tem `-` em suas versões) e não pode ser derivado usando `DISTVERSION` porque após a versão 9.9.9, será lançado "patchlevels" na forma `9.9.9-P1`. DISTVERSION iria traduzir isso para `9.9.9.p1`, que no esquema de versionamento de ports significa 9.9.9 pré-release 1, que vem antes de 9.9.9 e não depois. Assim `PORTVERSION` é derivado manualmente de uma variável `ISCVERSION` para retornar `9.9.9p1`. A ordem na qual o framework do ports e o pkg ordenará as versões, é verificada usando o argumento `-t` do man:pkg-version[8]: [source,shell] .... % pkg version -t 9.9.9 9.9.9.p1 > <.> % pkg version -t 9.9.9 9.9.9p1 < <.> .... <.> O sinal `>` significa que o primeiro argumento passado em `-t` é maior que o segundo argumento. `9.9.9` é maior que `9.9.9.p1`. <.> O sinal `<` significa que o primeiro argumento passado em `-t` é menor que o segundo argumento. `9.9.9` é menor que `9.9.9p1`. No [.filename]#Makefile# do port, por exemplo package:dns/bind99[], é alcançado por: [.programlisting] .... PORTNAME= bind PORTVERSION= ${ISCVERSION:S/-P/P/:S/b/.b/:S/a/.a/:S/rc/.rc/} <.> CATEGORIES= dns net MASTER_SITES= ISC/bind9/${ISCVERSION} <.> PKGNAMESUFFIX= 99 DISTNAME= ${PORTNAME}-${ISCVERSION} <.> MAINTAINER= mat@FreeBSD.org COMMENT= BIND DNS suite with updated DNSSEC and DNS64 LICENSE= ISCL # ISC releases things like 9.8.0-P1 or 9.8.1rc1, which our versioning does not like ISCVERSION= 9.9.9-P6 <.> .... <.> Defina a versão upstream em `ISCVERSION`, com um comentário dizendo _porque_ é necessário. <.> Use `ISCVERSION` para obter um `PORTVERSION` compatível com o ports. <.> Use `ISCVERSION` diretamente para obter a URL correta para baixar o arquivo de distribuição. <.> Use `ISCVERSION` diretamente para nomear o arquivo de distribuição. ==== [[makefile-distname-ex2]] .Derivar `DISTNAME` a partir de `PORTVERSION` [example] ==== De tempos em tempos, o nome do arquivo de distribuição tem pouca ou nenhuma relação com a versão do software. No package:comms/kermit[], apenas o último elemento da versão está presente no arquivo de distribuição: [.programlisting] .... PORTNAME= kermit PORTVERSION= 9.0.304 CATEGORIES= comms ftp net MASTER_SITES= ftp://ftp.kermitproject.org/kermit/test/tar/ DISTNAME= cku${PORTVERSION:E}-dev20 <.> .... <.> O modificador `:E` man:make[1] retorna o sufixo da variável, neste caso, `304`. O arquivo de distribuição `cku304-dev20.tar.gz` é gerado corretamente. ==== [[makefile-distname-ex3]] .Caso Exótico 1 [example] ==== Às vezes, não há relação entre o nome do software, sua versão e o arquivo de distribuição no qual ele é distribuído. Do package:audio/libworkman[]: [.programlisting] .... PORTNAME= libworkman PORTVERSION= 1.4 CATEGORIES= audio MASTER_SITES= LOCAL/jim DISTNAME= ${PORTNAME}-1999-06-20 .... ==== [[makefile-distname-ex4]] .Caso Exótico 2 [example] ==== No package:comms/librs232[], o arquivo de distribuição não é versionado, portanto, <> é necessário: [.programlisting] .... PORTNAME= librs232 PORTVERSION= 20160710 CATEGORIES= comms MASTER_SITES= http://www.teuniz.net/RS-232/ DISTNAME= RS-232 DIST_SUBDIR= ${PORTNAME}-${PORTVERSION} .... ==== [NOTE] ==== `PKGNAMEPREFIX` e `PKGNAMESUFFIX` não afetam o `DISTNAME`. Observe também que se `WRKSRC` for igual a [.filename]#${WRKDIR}/${DISTNAME}# enquanto o arquivo fonte original é nomeado para algo diferente de `${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}`, deixe `DISTNAME` sozinho-- definir apenas `DISTFILES` é mais fácil que ambos `DISTNAME` e `WRKSRC` (e possivelmente `EXTRACT_SUFX`). ==== [[makefile-master_sites]] === `MASTER_SITES` Grave a parte do diretório do FTP/HTTP-URL apontando para o tarball original em `MASTER_SITES`. Não esqueça a barra final ([.filename]#/#)! A macro `make` irá tentar usar esta especificação para baixar o arquivo de distribuição com `FETCH` se não for possível encontrá-lo já no sistema. Recomenda-se que vários sites sejam incluídos nesta lista, de preferência em diferentes continentes. Isso irá proteger contra problemas de rede amplos. [IMPORTANT] ==== `MASTER_SITES` não deve estar em branco. Ele deve apontar para o site real que hospeda os arquivos de distribuição. Ele não pode apontar para web archives ou para os sites de cache dos arquivos de distribuição do FreeBSD. A única exceção a essa regra são ports que não possuem arquivos de distribuição. Por exemplo, meta-ports não possuem arquivos de distribuição, assim o `MASTER_SITES` não precisa ser definido. ==== [[makefile-master_sites-shorthand]] ==== Usando Variáveis `MASTER_SITE_*`​​ Abreviações de atalhos estão disponíveis para arquivos populares como o SourceForge (`SOURCEFORGE`), GNU (`GNU`), ou Perl CPAN (`PERL_CPAN`). `MASTER_SITES` pode usá-los diretamente: [.programlisting] .... MASTER_SITES= GNU/make .... O antigo formato expandido ainda funciona, mas todos os ports foram convertidos para o formato compacto. O formato expandido se parece com isto: [.programlisting] .... MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make .... Estes valores e variáveis ​​são definidos em https://svnweb.freebsd.org/ports/head/Mk/bsd.sites.mk?view=markup[Mk/bsd.sites.mk]. Novas entradas são adicionadas com frequência, portanto, verifique a versão mais recente deste arquivo antes de enviar um port. [TIP] ==== Para qualquer variável `MASTER_SITE_FOO` , a versão abreviada `_FOO_` pode ser utilizada. Por exemplo, use: [.programlisting] .... MASTER_SITES= FOO .... E se `MASTER_SITE_SUBDIR` for necessário, use isso: [.programlisting] .... MASTER_SITES= FOO/bar .... ==== [NOTE] ==== Alguns nomes `MASTER_SITE_*` são bastante longos e, para facilitar o uso, foram definidos atalhos: [[makefile-master_sites-shortcut]] .Atalhos para Macros `MASTER_SITE_*` [cols="1,1", frame="none", options="header"] |=== | Macro | Atalho |`PERL_CPAN` |`CPAN` |`GITHUB` |`GH` |`GITHUB_CLOUD` |`GHC` |`LIBREOFFICE_DEV` |`LODEV` |`NETLIB` |`NL` |`RUBYGEMS` |`RG` |`SOURCEFORGE` |`SF` |=== ==== [[makefile-master_sites-magic]] ==== Macros Mágicas de MASTER_SITES Várias macros "mágicas" existem para sites populares com uma estrutura de diretórios previsível. Para isso, basta usar a abreviação e o sistema escolherá um subdiretório automaticamente. Para um port nomeado `Stardict`, de versão `1.2.3` e hospedado no SourceForge, adicione esta linha: [.programlisting] .... MASTER_SITES= SF .... Implica em um subdiretório chamado `/project/stardict/stardict/1.2.3`. Se o diretório estiver incorreto, ele poderá ser substituído: [.programlisting] .... MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... Isso também pode ser escrito como [.programlisting] .... MASTER_SITES= SF MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... [[makefile-master_sites-popular]] .Macros Mágicas de `MASTER_SITES` [cols="1,1", frame="none", options="header"] |=== | Macro | Subdiretório deduzido |`APACHE_COMMONS_BINARIES` |`${PORTNAME:S,commons-,,}` |`APACHE_COMMONS_SOURCE` |`${PORTNAME:S,commons-,,}` |`APACHE_JAKARTA` |`${PORTNAME:S,-,/,}/source` |`BERLIOS` |`${PORTNAME:tl}.berlios` |`CHEESESHOP` |`source/${DISTNAME:C/(.).\*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}` |`CPAN` |`${PORTNAME:C/-.*//}` |`DEBIAN` |`pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}` |`FARSIGHT` |`${PORTNAME}` |`FESTIVAL` |`${PORTREVISION}` |`GCC` |`releases/${DISTNAME}` |`GENTOO` |`distfiles` |`GIMP` |`${PORTNAME}/${PORTVERSION:R}/` |`GH` |`${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/` |`GHC` |`${GH_ACCOUNT}/${GH_PROJECT}/` |`GNOME` |`sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}` |`GNU` |`${PORTNAME}` |`GNUPG` |`${PORTNAME}` |`GNU_ALPHA` |`${PORTNAME}` |`HORDE` |`${PORTNAME}` |`LODEV` |`${PORTNAME}` |`MATE` |`${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}` |`MOZDEV` |`${PORTNAME:tl}` |`NL` |`${PORTNAME}` |`QT` |`archive/qt/${PORTVERSION:R}` |`SAMBA` |`${PORTNAME}` |`SAVANNAH` |`${PORTNAME:tl}` |`SF` |`${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION}` |=== [[makefile-master_sites-github]] === `USE_GITHUB` Se o arquivo de distribuição vier de um commit ou tag específico no https://github.com[GitHub] para o qual não há arquivo lançado oficialmente, há uma maneira fácil de definir o `DISTNAME` e `MASTER_SITES` corretos automaticamente. Estas variáveis ​​estão disponíveis: [[makefile-master_sites-github-description]] .`USE_GITHUB` Descrição [cols="1,1,1", options="header"] |=== | Variável | Descrição | Padrão |`GH_ACCOUNT` |Nome da conta do usuário do GitHub que hospeda o projeto |`${PORTNAME}` |`GH_PROJECT` |Nome do projeto no GitHub |`${PORTNAME}` |`GH_TAGNAME` |Nome da tag para download (2.0.1, hash, ...) Usar o nome de uma branch aqui é errado. Também é possível usar o hash de um ID de commit para gerar um snapshot. |`${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}` |`GH_SUBDIR` |Quando o software precisa que um arquivo de distribuição adicional seja extraído em `${WRKSRC}`, esta variável pode ser usada. Veja os exemplos em <> para maiores informações. |(none) |`GH_TUPLE` |`GH_TUPLE` permite colocar `GH_ACCOUNT`, `GH_PROJECT`, `GH_TAGNAME` e `GH_SUBDIR` em uma única variável. O formato é _conta_`:`_projeto_`:`_tagname_`:`_grupo_`/`_subdiretório_. O `/`_subdiretório _ é opcional. Isso é útil quando mais de um projeto no GitHub precisa ser utilizado. |=== [IMPORTANT] ==== Não use `GH_TUPLE` para o arquivo de distribuição padrão, já que não tem nenhum padrão. ==== [[makefile-master_sites-github-ex1]] .Uso Simples de `USE_GITHUB` [example] ==== Ao tentar fazer um port para a versão `1.2.7` do pkg do usuário FreeBSD no github, em https://github.com/freebsd/pkg[], O [.filename]#Makefile# acabaria ficando assim (levemente simplificado para o exemplo): [.programlisting] .... PORTNAME= pkg DISTVERSION= 1.2.7 USE_GITHUB= yes GH_ACCOUNT= freebsd .... `MASTER_SITES` será automaticamente definido como `GH GHC` e `WRKSRC` para `${WRKDIR}/pkg-1.2.7`. ==== [[makefile-master_sites-github-ex2]] .Uso Mais Completo de `USE_GITHUB` [example] ==== Ao tentar fazer um port para uma versão de desenvolvimento do pkg do usuário FreeBSD no github, em https://github.com/freebsd/pkg[], o [.filename]#Makefile# acaba ficando assim (levemente simplificado para o exemplo): [.programlisting] .... PORTNAME= pkg-devel DISTVERSION= 1.3.0.a.20140411 USE_GITHUB= yes GH_ACCOUNT= freebsd GH_PROJECT= pkg GH_TAGNAME= 6dbb17b .... `MASTER_SITES` será automaticamente definido para `GH GHC` e `WRKSRC` para `${WRKDIR}/pkg-6dbb17b`. [TIP] ====== `20140411` é a data do commit referenciada em `GH_TAGNAME`, não a data em que é editado o [.filename]#Makefile#, ou a data em que o commit é feito. ====== ==== [[makefile-master_sites-github-ex3]] .Uso de `USE_GITHUB` com `DISTVERSIONPREFIX` [example] ==== De tempos em tempos, `GH_TAGNAME` é uma ligeira variação de `DISTVERSION`. Por exemplo, se a versão for `1.0.2`, e a tag `v1.0.2`. Nesses casos, é possível usar `DISTVERSIONPREFIX` ou `DISTVERSIONSUFFIX`: [.programlisting] .... PORTNAME= foo DISTVERSIONPREFIX= v DISTVERSION= 1.0.2 USE_GITHUB= yes .... `GH_TAGNAME` será automaticamente definido para `v1.0.2`, enquanto `WRKSRC` será mantido como `${WRKDIR} /foo-1.0.2`. ==== [[makefile-master_sites-github-ex4]] .Usando `USE_GITHUB` Quando o Upstream Não Usa Versões [example] ==== Se nunca houve uma versão upstream, não invente uma como `0.1` ou `1.0`. Crie o port com um `DISTVERSION` de `gYYYYMMDD`, onde `g` é para Git e `YYYYMMDD` representa a data em que o commit é referenciado em `GH_TAGNAME`. [.programlisting] .... PORTNAME= bar DISTVERSION= g20140411 USE_GITHUB= yes GH_TAGNAME= c472d66b .... Isso cria um esquema de controle de versão que é incrementado com o tempo e que ainda é menor do que a versão `0` (veja <> para mais informações do man:pkg-version[8]): [source,shell] .... % pkg version -t g20140411 0 < .... Isso significa que não será necessário usar o `PORTEPOCH` caso o upstream decida lançar versões no futuro. ==== [[makefile-master_sites-github-ex5]] .Usando `USE_GITHUB` para Acessar um Commit Entre Duas Versões [example] ==== Se a versão atual do software usa uma tag Git, e o port precisa ser atualizado para uma versão mais recente e intermediária, sem uma tag, use man:git-describe[1] para descobrir a versão a ser utilizada: [source,shell] .... % git describe --tags f0038b1 v0.7.3-14-gf0038b1 .... `v0.7.3-14-gf0038b1` pode ser dividido em três partes: `v0.7.3`:: Este é a última tag Git que aparece no histórico de commits antes do commit solicitado. `-14`:: Isso significa que o commit solicitado, `f0038b1`, é o 14º commit após a tag `v0.7.3`. `-gf0038b1`:: O `-g` significa "Git", e o `f0038b1` é o commit hash referenciado. [.programlisting] .... PORTNAME= bar DISTVERSIONPREFIX= v DISTVERSION= 0.7.3-14 DISTVERSIONSUFFIX= -gf0038b1 USE_GITHUB= yes .... Isso cria um esquema de versionamento que é incrementado com o tempo (bem, em cima de commits), e não entra em conflito com a criação de uma versão `0.7.4`. (Veja <> para detalhes do man:pkg-version[8]): [source,shell] .... % pkg version -t 0.7.3 0.7.3.14 < % pkg version -t 0.7.3.14 0.7.4 < .... [NOTE] ====== Se o commit solicitado é o mesmo que uma tag, uma descrição mais curta é mostrada por padrão. A versão mais longa é equivalente: [source,shell] .... % git describe --tags c66c71d v0.7.3 % git describe --tags --long c66c71d v0.7.3-0-gc66c71d .... ====== ==== [[makefile-master_sites-github-multiple]] ==== Baixando Múltiplos Arquivos do GitHub O framework `USE_GITHUB` também suporta a obtenção de vários arquivos de distribuição de diferentes locais no GitHub. Ele funciona de uma forma muito semelhante ao <>. Vários valores são adicionados a `GH_ACCOUNT`, `GH_PROJECT` e `GH_TAGNAME`. Cada valor diferente é atribuído a um grupo. O valor principal pode não ter nenhum grupo ou grupo `:DEFAULT`. Um valor pode ser omitido se for o mesmo que o padrão listado em <>. `GH_TUPLE` também pode ser usado quando há muitos arquivos de distribuição. Isso ajuda a manter as informações de conta, projeto, tagname e grupo no mesmo lugar. Para cada grupo, uma variável auxiliar `${WRKSRC_group}` é criada, contendo o diretório no qual o arquivo foi extraído. As variáveis `${WRKSRC_group}` ​​podem ser usadas para mover diretórios durante o `post-extract`, ou para serem adicionadas em `CONFIGURE_ARGS`, ou o que for necessário para que o software seja compilado corretamente. [CAUTION] ==== A parte do `:group` _deve_ ser usada para _apenas um_ arquivo de distribuição. Ela é usado como uma chave única e usá-la mais de uma vez irá sobrescrever os valores anteriores. ==== [NOTE] ==== Como isso é apenas modificações de `DISTFILES` e `MASTER_SITES`, os nomes dos grupos devem obedecer às restrições de nomes de grupos descritas em <> ==== Ao buscar vários arquivos do GitHub, às vezes o arquivo de distribuição padrão não é buscado no GitHub. Para desabilitar a busca da distribuição padrão, defina: [.programlisting] .... USE_GITHUB= nodefault .... [IMPORTANT] ==== Ao utilizar `USE_GITHUB=nodefault`, o [.filename]#Makefile# deve ter `DISTFILES` em seu <>. A definição deve ser: [.programlisting] .... DISTFILES= ${DISTNAME}${EXTRACT_SUFX} .... ==== [[makefile-master_sites-github-multi]] .Uso de `USE_GITHUB` com Vários Arquivos de Distribuição [example] ==== De tempos em tempos é necessário baixar mais de um arquivo de distribuição. Por exemplo, quando o repositório git do upstream usa submódulos. Isso pode ser feito facilmente usando grupos nas variáveis `GH_*`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITHUB= yes GH_ACCOUNT= bar:icons,contrib GH_PROJECT= foo-icons:icons foo-contrib:contrib GH_TAGNAME= 1.0:icons fa579bc:contrib GH_SUBDIR= ext/icons:icons CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Isso irá baixar três arquivos de distribuição do github. O padrão vem de [.filename]#foo/foo# versão `1.0.2`. O segundo, com o grupo `icons`, vem de [.filename]#bar/foo-icons# versão `1.0`. O terceiro vem de [.filename]#bar/foo-contrib# e usa o commit do Git `fa579bc`. Os arquivos de distribuição são nomeados [.filename]#foo-foo-1.0.2_GH0.tar.gz#, [.filename]#bar-foo-icons-1.0_GH0.tar.gz# e [.filename]#bar-foo-contrib-fa579bc_GH0.tar.gz#. Todos os arquivos de distribuição são extraídos em `${WRKDIR}` em seus respectivos subdiretórios. O arquivo padrão ainda é extraído em `${WRKSRC}`, nesse caso, [.filename]#${WRKDIR}/foo-1.0.2#. Cada arquivo de distribuição adicional é extraído em `${WRKSRC_group}`. Aqui, para o grupo `icons`, chamado de `${WRKSRC_icons}`, será [.filename]#${WRKDIR}/foo-icons-1.0#. O arquivo com o grupo `contrib` é chamado de `${WRKSRC_contrib}` e contém `${WRKDIR}/foo-contrib-fa579bc`. O sistema de compilação do software espera encontrar os ícones em um subdiretório [.filename]#ext/icons# em seus fontes, então `GH_SUBDIR` é usado. `GH_SUBDIR` garante que [.filename]#ext# exista, mas não que [.filename]#ext/icons# também exista. Então isso acontece: [.programlisting] .... post-extract: @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons .... ==== [[makefile-master_sites-github-multi2]] .Uso de `USE_GITHUB` com Vários Arquivos de Distribuição Usando `GH_TUPLE` [example] ==== Isto é funcionalmente equivalente a <> mas usando `GH_TUPLE`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITHUB= yes GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ bar:foo-contrib:fa579bc:contrib CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Agrupamento foi usado no exemplo anterior com `bar:icons, contrib`. Algumas informações redundantes estão presentes com `GH_TUPLE` porque o uso de agrupamento não é possível. ==== [[makefile-master_sites-github-submodules]] .Como Usar `USE_GITHUB` com Submodulos Git? [example] ==== Ports com o GitHub como um repositório upstream às vezes usam submódulos. Veja man:git-submodule[1] para maiores informações. O problema com submódulos é que cada um é um repositório separado. Como tal, cada um deve ser buscado separadamente. Usando package:finances/moneymanagerex[] como exemplo, seu repositório GitHub é https://github.com/moneymanagerex/moneymanagerex[]. Tem um arquivo https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules[.gitmodules] na raiz. Este arquivo descreve todos os sub módulos usados neste repositório e lista os repositórios adicionais necessários. Este arquivo irá dizer quais repositórios adicionais são necessários: [.programlisting] .... [submodule "lib/wxsqlite3"] path = lib/wxsqlite3 url = https://github.com/utelle/wxsqlite3.git [submodule "3rd/mongoose"] path = 3rd/mongoose url = https://github.com/cesanta/mongoose.git [submodule "3rd/LuaGlue"] path = 3rd/LuaGlue url = https://github.com/moneymanagerex/LuaGlue.git [submodule "3rd/cgitemplate"] path = 3rd/cgitemplate url = https://github.com/moneymanagerex/html-template.git [...] .... A única informação que falta nesse arquivo é a hash ou tag de commit para usar na versão. Esta informação é encontrada após a clonagem do repositório: [source,shell] .... % git clone --recurse-submodules https://github.com/moneymanagerex/moneymanagerex.git Cloning into 'moneymanagerex'... remote: Counting objects: 32387, done. [...] Submodule '3rd/LuaGlue' (https://github.com/moneymanagerex/LuaGlue.git) registered for path '3rd/LuaGlue' Submodule '3rd/cgitemplate' (https://github.com/moneymanagerex/html-template.git) registered for path '3rd/cgitemplate' Submodule '3rd/mongoose' (https://github.com/cesanta/mongoose.git) registered for path '3rd/mongoose' Submodule 'lib/wxsqlite3' (https://github.com/utelle/wxsqlite3.git) registered for path 'lib/wxsqlite3' [...] Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/LuaGlue'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/cgitemplate'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/mongoose'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/lib/wxsqlite3'... [...] Submodule path '3rd/LuaGlue': checked out 'c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b' Submodule path '3rd/cgitemplate': checked out 'cd434eeeb35904ebcd3d718ba29c281a649b192c' Submodule path '3rd/mongoose': checked out '2140e5992ab9a3a9a34ce9a281abf57f00f95cda' Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7d6b51' [...] % cd moneymanagerex % git submodule status c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b 3rd/LuaGlue (heads/master) cd434eeeb35904ebcd3d718ba29c281a649b192c 3rd/cgitemplate (cd434ee) 2140e5992ab9a3a9a34ce9a281abf57f00f95cda 3rd/mongoose (6.2-138-g2140e59) fb66eb230d8aed21dec273b38c7c054dcb7d6b51 lib/wxsqlite3 (v3.4.0) [...] .... Também pode ser encontrado no GitHub. Cada subdiretório que é um submódulo é mostrado como _diretório_ `@` _hash_, por exemplo,`mongoose @ 2140e59`. [NOTE] ====== Embora a obtenção das informações pelo GitHub pareça mais fácil, as informações encontradas usando `git submodule status` fornecerá informações mais significativas. Por exemplo, o commit hash de `lib/wxsqlite3 fb66eb2` corresponde a `v3.4.0`. Ambos podem ser usados, mas quando uma tag estiver disponível, use-a. ====== Agora que todas as informações necessárias foram reunidas, o [.filename]#Makefile# pode ser escrito (somente as linhas relacionadas ao GitHub são mostradas): [.programlisting] .... PORTNAME= moneymanagerex DISTVERSIONPREFIX= v DISTVERSION= 1.3.0 USE_GITHUB= yes GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \ moneymanagerex:LuaGlue:c51d11a:lua_glue/3rd/LuaGlue \ moneymanagerex:html-template:cd434ee:html_template/3rd/cgitemplate \ cesanta:mongoose:2140e59:mongoose/3rd/mongoose \ [...] .... ==== [[makefile-master_sites-gitlab]] === `USE_GITLAB` Semelhante ao GitHub, se o arquivo de distribuição vier de https://gitlab.com[gitlab.com] ou se estiver hospedado com o software GitLab, essas variáveis estão disponíveis para uso e talvez precisem ser definidas. [[makefile-master_sites-gitlab-description]] .`USE_GITLAB` Descrição [cols="1,1,1", options="header"] |=== | Variável | Descrição | Padrão |`GL_SITE` |Nome do site que hospeda o projeto GitLab |https://gitlab.com |`GL_ACCOUNT` |Nome da conta do usuário do GitLab hospedando o projeto |`${PORTNAME}` |`GL_PROJECT` |Nome do projeto em GitLab |`${PORTNAME}` |`GL_COMMIT` |O hash de commit para download. Deve ser o hash hex sha1 completo de 160 bits e 40 caracteres. Essa é uma variável obrigatória para GitLab. |`(none)` |`GL_SUBDIR` |Quando o software precisa de um arquivo de distribuição adicional para ser extraído com `${WRKSRC}`, esta variável pode ser usada. Veja os exemplos em <> para maiores informações. |(none) |`GL_TUPLE` |`GL_TUPLE` permite colocar `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT`, `GL_COMMIT`, e `GL_SUBDIR` dentro de uma única variável. O formato é _site_`:`_conta_`:`_projeto_`:`_commit_`:`_grupo_`/`_subdiretório_. O _site_`:` e `/`_subdiretório_ são opcionais. Isso ajuda quando é necessário baixar arquivos de mais de um projeto GitLab. |=== [[makefile-master_sites-gitlab-ex1]] .Uso Simples de `USE_GITLAB` [example] ==== Ao tentar fazer um port para a versão `1.14` do libsignon-glib do usuário accounts-sso do gitlab.com, em https://gitlab.com/accounts-sso/libsignon-glib[], O [.filename]#Makefile# acabaria ficando assim para buscar os arquivos de distribuição: [.programlisting] .... PORTNAME= libsignon-glib DISTVERSION= 1.14 USE_GITLAB= yes GL_ACCOUNT= accounts-sso GL_COMMIT= e90302e342bfd27bc8c9132ab9d0ea3d8723fd03 .... Ele terá automaticamente `MASTER_SITES` definido como https://gitlab.com[gitlab.com] e `WRKSRC` para `${WRKDIR}/libsignon-glib-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03`. ==== [[makefile-master_sites-gitlab-ex2]] .Uso Mais Completo de `USE_GITLAB` [example] ==== Um uso mais completo do exemplo acima é se o port não tiver controle de versão e foobar do usuário foo no projeto bar em um GitLab auto hospedado em `https://gitlab.example.com`, o [.filename]#Makefile# acaba ficando assim para buscar os arquivos de distribuição: [.programlisting] .... PORTNAME= foobar DISTVERSION= g20170906 USE_GITLAB= yes GL_SITE= https://gitlab.example.com GL_ACCOUNT= foo GL_PROJECT= bar GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6 .... Terá `MASTER_SITES` definido como `"https://gitlab.example.com"` e `WRKSRC` para `${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6`. [TIP] ====== `20170906` é a data do commit referenciada em `GL_COMMIT`, não a data em que o [.filename]#Makefile# é editado, ou a data em que o commit para a árvore de ports do FreeBSD é feito. ====== [NOTE] ====== O protocolo, porta e webroot do `GL_SITE` podem ser modificados na mesma variável. ====== ==== [[makefile-master_sites-gitlab-multiple]] ==== Baixando Múltiplos Arquivos do GitLab O framework `USE_GITLAB` também suporta a busca de vários arquivos de distribuição de diferentes locais de GitLab e sites hospedados no GitLab. Ele funciona de uma forma muito semelhante ao <> e <>. Vários valores são adicionados a `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` e `GL_COMMIT`. Cada valor diferente é atribuído a um grupo. <>. `GL_TUPLE` também pode ser usado quando há muitos arquivos de distribuição. Isso ajuda a manter as informações de site, conta, projeto, commit e grupo no mesmo local. Para cada grupo, uma variável auxiliar `${WRKSRC_group}` é criada, contendo o diretório no qual o arquivo foi extraído. As variáveis `${WRKSRC_group}` ​​podem ser usadas para mover diretórios durante o `post-extract`, ou para serem adicionadas em `CONFIGURE_ARGS`, ou o que for necessário para que o software seja compilado corretamente. [CAUTION] ==== A parte do `:group` _deve_ ser usada para _apenas um_ arquivo de distribuição. Ela é usado como uma chave única e usá-la mais de uma vez irá sobrescrever os valores anteriores. ==== [NOTE] ==== Como isso é apenas modificações de `DISTFILES` e `MASTER_SITES`, os nomes dos grupos devem obedecer às restrições de nomes de grupos descritas em <> ==== Ao buscar vários arquivos usando GitLab, às vezes, o arquivo de distribuição padrão não é obtido de um GitLab. Para desativar a busca do arquivo de distribuição padrão, defina: [.programlisting] .... USE_GITLAB= nodefault .... [IMPORTANT] ==== Ao utilizar `USE_GITLAB=nodefault`, o [.filename]#Makefile# deve ter `DISTFILES` em seu <>. A definição deve ser: [.programlisting] .... DISTFILES= ${DISTNAME}${EXTRACT_SUFX} .... ==== [[makefile-master_sites-gitlab-multi]] .Uso de `USE_GITLAB` com Vários Arquivos de Distribuição [example] ==== De tempos em tempos, é necessário buscar mais de um arquivo de distribuição. Por exemplo, quando o repositório git do upstream usa submódulos. Isso pode ser feito facilmente usando grupos nas variáveis `GL_*`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITLAB= yes GL_SITE= https://gitlab.example.com:9434/gitlab:icons GL_ACCOUNT= bar:icons,contrib GL_PROJECT= foo-icons:icons foo-contrib:contrib GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b ae7368cab1ca7ca754b38d49da064df87968ffe4:icons 9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib GL_SUBDIR= ext/icons:icons CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Isso irá buscar dois arquivos de distribuição do gitlab.com e um de `gitlab.example.com` hospedado com GitLab. O padrão vem de [.filename]#https://gitlab.com/foo/foo# e o commit é `c189207a55da45305c884fe2b50e086fcad4724b`. O segundo, com o grupo `icons`, vem de [.filename]#https://gitlab.example.com:9434/gitlab/bar/foo-icons# e o commit é `ae7368cab1ca7ca754b38d49da064df87968ffe4`. O terceiro vem de [.filename]#https://gitlab.com/bar/foo-contrib# e o commit é `9e4dd76ad9b38f33fdb417a4c01935958d5acd2a`. Os arquivos de distribuição são nomeados [.filename]#foo-foo-c189207a55da45305c884fe2b50e086fcad4724b_GL0.tar.gz#, [.filename]#bar-foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4_GL0.tar.gz# e [.filename]#bar-foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a_GL0.tar.gz#. Todos os arquivos de distribuição são extraídos no `${WRKDIR}` em seus respectivos subdiretórios. O arquivo padrão ainda é extraído no `${WRKSRC}`, nesse caso, [.filename]#${WRKDIR}/foo-c189207a55da45305c884fe2b50e086fcad4724b-c189207a55da45305c884fe2b50e086fcad4724b#. Cada arquivo de distribuição adicional é extraído em `${WRKSRC_group}`. Aqui, para o grupo `icons`, é chamado `${WRKSRC_icons}` e contém [.filename]#${WRKDIR}/foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4-ae7368cab1ca7ca754b38d49da064df87968ffe4#. O arquivo com o grupo `contrib` é chamado `${WRKSRC_contrib}` e contém `${WRKDIR}/foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a`. O sistema de compilação do software espera encontrar os ícones em um subdiretório [.filename]#ext/icons# em seus fontes, então `GL_SUBDIR` é usado.`GL_SUBDIR` garante que [.filename]#ext# existe, mas não que [.filename]#ext/icons# também exista. Então isso acontece: [.programlisting] .... post-extract: @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons .... ==== [[makefile-master_sites-gitlab-multi2]] .Uso de `USE_GITLAB` com Vários Arquivos de Distribuição Usando `GL_TUPLE` [example] ==== Isto é funcionalmente equivalente a <> mas usando `GL_TUPLE`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITLAB= yes GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b GL_TUPLE= https://gitlab.example.com:9434/gitlab:bar:foo-icons:ae7368cab1ca7ca754b38d49da064df87968ffe4:icons/ext/icons \ bar:foo-contrib:9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Agrupamento foi usado no exemplo anterior com `bar:icons,contrib`. Algumas informações redundantes estão presentes com `GL_TUPLE` porque o uso de agrupamento não é possível. ==== [[makefile-extract_sufx]] === `EXTRACT_SUFX` Se houver um arquivo de distribuição e ele usar um sufixo diferente para indicar o mecanismo de compactação, defina `EXTRACT_SUFX`. Por exemplo, se o arquivo de distribuição foi nomeado [.filename]#foo.tar.gzip# em vez do mais comum [.filename]#foo.tar.gz#, escreva: [.programlisting] .... DISTNAME= foo EXTRACT_SUFX= .tar.gzip .... -O `USES=tar[:xxx]`, `USES=lha` ou `USES=zip` define automaticamente `EXTRACT_SUFX` com as extensões de arquivo mais comuns, conforme necessário, consulte <> para mais detalhes. Se nenhum destes estiver definido, o `EXTRACT_SUFX` padrão é `.tar.gz`. +O `USES=tar[:xxx]`, `USES=lha` ou `USES=zip` define automaticamente `EXTRACT_SUFX` com as extensões de arquivo mais comuns, conforme necessário, consulte crossref:uses[uses, Usando Macros `USES`] para mais detalhes. Se nenhum destes estiver definido, o `EXTRACT_SUFX` padrão é `.tar.gz`. [NOTE] ==== Como `EXTRACT_SUFX` é usado apenas em `DISTFILES`, apenas defina um deles.. ==== [[makefile-distfiles-definition]] === `DISTFILES` Às vezes os nomes dos arquivos a serem baixados não têm semelhança com o nome do port. Por exemplo, pode ser chamado [.filename]#source.tar.gz# ou similar. Em outros casos, o código-fonte do aplicativo pode estar em vários arquivos diferentes, e todos eles devem ser baixados. Se este for o caso, defina `DISTFILES` para ser uma lista separada por espaços de todos os arquivos que devem ser baixados. [.programlisting] .... DISTFILES= source1.tar.gz source2.tar.gz .... Se não for definido explicitamente, o `DISTFILES` padrão é `${DISTNAME}${EXTRACT_SUFX}`. [[makefile-extract_only]] === `EXTRACT_ONLY` Se apenas alguns dos `DISTFILES` devem ser extraídos-- por exemplo, um deles é o código-fonte, enquanto outro é um documento não compactado - liste os nomes dos arquivos que devem ser extraídos em `EXTRACT_ONLY`. [.programlisting] .... DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz .... Quando nenhum dos `DISTFILES` precisam ser descompactados, deixe vazio o `EXTRACT_ONLY`. [.programlisting] .... EXTRACT_ONLY= .... [[porting-patchfiles]] === `PATCHFILES` Se o port requer alguns patches adicionais que estão disponíveis por FTP ou HTTP, defina `PATCHFILES` para os nomes dos arquivos e `PATCH_SITES` para a URL do diretório que os contém (o formato é o mesmo do `MASTER_SITES`). Se o patch não for relativo ao inicio da árvore do código fonte (isto é, `WRKSRC`) porque contém alguns pathnames extras, defina `PATCH_DIST_STRIP` adequadamente. Por exemplo, se todos os pathnames no patch tiverem um `foozolix-1.0 /` extra na frente dos nomes dos arquivos, então defina `PATCH_DIST_STRIP=-p1`. Não se preocupe se os patches estiverem compactados; eles serão descompactados automaticamente se os nomes dos arquivos terminarem com [.filename]#.Z#, [.filename]#.gz#, [.filename]#.bz2# ou [.filename]#.xz#. Se o patch for distribuído com alguns outros arquivos, como documentação, em um arquivo compactado, o uso de `PATCHFILES` não será possível. Se for esse o caso, adicione o nome e a localização do arquivo do patch em `DISTFILES` e `MASTER_SITES`. Então, use `EXTRA_PATCHES` para apontar para esses arquivos e o [.filename]#bsd.port.mk# irá aplicá-los automaticamente. Em particular, _não_ copie os arquivos de patch em [.filename]#${PATCHDIR}#. Esse diretório pode não ter permissão de escrita. [TIP] ==== Se houver vários patches e eles precisarem de valores mistos para o parâmetro strip, ele poderá ser adicionado ao lado do nome do patch em `PATCHFILES`, por exemplo: [.programlisting] .... PATCHFILES= patch1 patch2:-p1 .... Isto não entra em conflito com <>, adicionando um grupo também funciona: [.programlisting] .... PATCHFILES= patch2:-p1:source2 .... ==== [NOTE] ==== O arquivo será extraído junto com o arquivo de código fonte, então não há necessidade de explicitamente extraí-lo se ele for um arquivo compactado normal. Tome cuidado extra para não sobrescrever algo que já existe nesse diretório caso faça a extração manualmente. Também não se esqueça de adicionar um comando para remover o patch copiado no target `pre-clean`. ==== [[porting-master-sites-n]] === Múltiplos Arquivos de Distribuição ou Patches de Vários Locais (Considere isto como um "tópico avançado"; a princípio, aqueles que são novos neste documento podem desejar pular esta seção). Esta seção contém informações sobre o mecanismo de busca conhecido como `MASTER_SITES:n` e `MASTER_SITES_NN`. Vamos nos referir a este mecanismo como `MASTER_SITES:n`. Um pouco de background primeiro. O OpenBSD tem um ótimo recurso dentro do `DISTFILES` e `PATCHFILES` que permite que arquivos e pacthes sejam pós fixados com identificadores `:n`. Aqui, `n` pode ser qualquer palavra que contenha `[0-9a-zA-Z_]` e signifique uma designação de grupo. Por exemplo: [.programlisting] .... DISTFILES= alpha:0 beta:1 .... No OpenBSD, arquivo de distribuição [.filename]#alpha# será associado com a variável `MASTER_SITES0` em vez da nossa comum `MASTER_SITES` e [.filename]#beta# com `MASTER_SITES1`. Esta é uma característica muito interessante que pode diminuir a busca sem fim pelo site de download correto. Apenas imagine 2 arquivos em `DISTFILES` e 20 sites em `MASTER_SITES`, os sites são extremamente lentos e [.filename]#beta# é hospedado em todas as entradas do `MASTER_SITES` e [.filename]#alfa# só pode ser encontrado no 20º site. Seria um desperdício checar todos eles se o mantenedor soubesse isso de antemão, não seria? Não é um bom começo para aquele lindo fim de semana! Agora que você já tem uma ideia, imagine mais `DISTFILES` e mais `MASTER_SITES`. Certamente nosso "distfiles survey meister" irá ser apreciado pelo alívio nas conexões de rede que isso trará. Nas próximas seções, as informações seguirão a implementação do FreeBSD desta idéia. Nós melhoramos um pouco o conceito do OpenBSD. [IMPORTANT] ==== Os nomes dos grupos não podem ter traços neles (`-`), na verdade, eles não podem ter nenhum caractere fora do range `[a-zA-Z0-9_]`. Isso porque, enquantoman:make[1] está ok com nomes de variáveis ​​contendo traços, man:sh[1]não. ==== [[porting-master-sites-n-simplified]] ==== Informação Simplificada Esta seção explica como preparar rapidamente a busca de vários arquivos de distribuição e patches de diferentes sites e subdiretórios. Descrevemos aqui um caso de uso de `MASTER_SITES:n`. Isso será suficiente para a maioria dos cenários. Informações mais detalhadas estão disponíveis em <>. Alguns aplicativos consistem em vários arquivos de distribuição que devem ser baixados de vários sites diferentes. Por exemplo, Ghostscript consiste no núcleo do programa e, em seguida, um grande número de arquivos de driver que são usados dependendo da impressora do usuário. Alguns desses arquivos de driver são fornecidos com o núcleo, mas muitos outros devem ser baixados de uma variedade de sites diferentes. Para suportar isso, cada entrada no `DISTFILES` pode ser seguida por dois pontos e um "nome de grupo". Cada site listado em `MASTER_SITES` é então seguido por dois pontos, e o grupo que indica quais arquivos de distribuição são baixados deste site. Por exemplo, considere um aplicativo com a divisão do código fonte em duas partes, [.filename]#source1.tar.gz# e [.filename]#source2.tar.gz#, que deve ser baixado de dois sites diferentes. O [.filename]#Makefile# do port incluiria linhas como <>. [[ports-master-sites-n-example-simple-use-one-file-per-site]] .Uso Simplificado de `MASTER_SITES:n` com Um Arquivo Por Site [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp1.example.com/:source1 \ http://www.example.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 .... ==== Vários arquivos de distribuição podem ter o mesmo grupo. Continuando o exemplo anterior, suponha que houvesse um terceiro distfile, [.filename]#source3.tar.gz#, que é baixado do `ftp.example2.com`. O [.filename]#Makefile# seria então escrito como <>. [[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]] .Uso Simplificado de `MASTER_SITES:n` com Mais de Um Arquivo Por Site [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp.example.com/:source1 \ http://www.example.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 \ source3.tar.gz:source2 .... ==== [[ports-master-sites-n-detailed]] ==== Informação Detalhada Ok, então o exemplo anterior não refletiu as necessidades do novo port? Nesta seção vamos explicar em detalhes como o mecanismo de busca avançado `MASTER_SITES:n` funciona e como ele pode ser usado. . Elementos podem ser pós-fixados com `:__n__` onde _n_ é `[^:,]+`, isso é, _n_ poderia conceitualmente ser qualquer string alfanumérica, mas vamos limitá-lo a `[a-zA-Z_][0-9a-zA-Z_]+` por enquanto. + Além disso, a verificação de strings é case sensitive, ou seja, `n` é diferente de `N`. + No entanto, essas palavras não podem ser usadas para finalidades de pós-fixação, pois elas produzem um significado especial: `default`, `all` e `ALL` (estes são usados ​​internamente no item <>). Além disso, `DEFAULT` é uma palavra de propósito especial (verifique o item <>). . Elementos pós-fixados com `:n` pertence ao grupo `n`, `:m` pertence ao grupo `m` e assim por diante. + [[porting-master-sites-n-DEFAULT-group]] . Elementos que não estão pós-fixados são desagrupados, todos eles pertencem ao grupo especial `DEFAULT`. Quaisquer elementos pós-fixados com `DEFAULT` estão apenas sendo redundantes, a menos que um elemento pertença a ambos `DEFAULT` e outros grupos ao mesmo tempo (verifique o item <>). + Esses exemplos são equivalentes, mas o primeiro é o preferido: + [.programlisting] .... MASTER_SITES= alpha .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT .... + . Grupos não são exclusivos, um elemento pode pertencer a vários grupos diferentes ao mesmo tempo e um grupo pode ter vários elementos diferentes ou nenhum. + [[porting-master-sites-n-comma-operator]] . Quando um elemento pertence a vários grupos ao mesmo tempo, use uma vírgula (`,`). + Em vez de repetir isso várias vezes, cada vez com uma pós-fixação diferente, podemos listar vários grupos de uma vez em uma única pós-fixação. Por exemplo, `:m,n,o` marca um elemento que pertence ao grupo `m`, `n` e `o`. + Todos esses exemplos são equivalentes, mas o último é o preferido: + [.programlisting] .... MASTER_SITES= alpha alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:SOME_SITE,DEFAULT .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT,SOME_SITE .... + . Todos os sites dentro de um determinado grupo são ordernados de acordo com `MASTER_SORT_AWK`. Todos os grupos dentro de `MASTER_SITES` e `PATCH_SITES` são ordenados também. + [[porting-master-sites-n-group-semantics]] . A semântica de grupo pode ser usada em qualquer uma das variáveis `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES` e `PATCHFILES` de acordo com esta sintaxe: .. Todos elementos `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` e `PATCH_SITE_SUBDIR` devem ser terminados com o caractere barra `/`. Se algum elemento pertencer a algum grupo, o grupo de pós-fixação `:__n__` deve vir logo após o terminador `/`. O mecanismo `MASTER_SITES:n` depende da existência do terminador `/` para evitar confundir elementos onde um `:n` é uma parte válida do elemento com ocorrências em que `:n` denota grupo `n`. Para fins de compatibilidade, uma vez que o terminador `/` não for necessário antes em ambos elementos `MASTER_SITE_SUBDIR` e `PATCH_SITE_SUBDIR`, se o caractere precedente imediato da pós-fixação não for `/` então `:n` será considerada uma parte válida do elemento em vez de uma pós-fixação de grupo, mesmo que um elemento `n` seja pós-fixado. Veja ambos <> e <>. + [[ports-master-sites-n-example-detailed-use-master-site-subdir]] .Uso Detalhado de `MASTER_SITES:n` no `MASTER_SITE_SUBDIR` [example] ==== [.programlisting] .... MASTER_SITE_SUBDIR= old:n new/:NEW .... *** Diretórios dentro do grupo `DEFAULT` -> old:n *** Diretórios dentro do grupo `NEW` -> new ==== + [[ports-master-sites-n-example-detailed-use-complete-example-master-sites]] .Uso Detalhado de `MASTER_SITES:n` com Vírgula, Vários Arquivos, Vários Sites e Vários Subdiretórios [example] ==== [.programlisting] .... MASTER_SITES= http://site1/%SUBDIR%/http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES= file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory .... O exemplo anterior resulta em uma busca detalhada. Os sites são listados na ordem exata em que serão usados. *** [.filename]#arquivo1# será obtido a partir de **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#arquivo2# será baixado exatamente como o [.filename]#arquivo1# já que ambos pertencem ao mesmo grupo **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#arquivo3# será obtido a partir de **** `MASTER_SITE_OVERRIDE` **** http://site3/ **** `MASTER_SITE_BACKUP` *** [.filename]#arquivo4# será obtido a partir de **** `MASTER_SITE_OVERRIDE` **** http://site4/ **** http://site5/ **** http://site6/ **** http://site7/ **** http://site8/directory-one/ **** `MASTER_SITE_BACKUP` *** [.filename]#arquivo5# será obtido a partir de **** `MASTER_SITE_OVERRIDE` **** `MASTER_SITE_BACKUP` *** [.filename]#file6# será obtido a partir de **** `MASTER_SITE_OVERRIDE` **** http://site8/ **** `MASTER_SITE_BACKUP` ==== . Como posso agrupar uma das macros especiais de [.filename]#bsd.sites.mk#, por exemplo, SourceForge (`SF`)? + Isso foi simplificado o máximo possível. Veja <>. + [[ports-master-sites-n-example-detailed-use-master-site-sourceforge]] .Uso Detalhado de `MASTER_SITES:n` com SourceForge (`SF`) [example] ==== [.programlisting] .... MASTER_SITES= http://site1/SF/something/1.0:sourceforge,TEST DISTFILES= something.tar.gz:sourceforge .... [.filename]#something.tar.gz# será obtido por todos os sites do SourceForge. ==== . Como eu uso isso com `PATCH*`? + Todos os exemplos foram feitos com `MASTER*` mas eles funcionam exatamente da mesma forma com `PATCH*` como pode ser visto em <>. + [[ports-master-sites-n-example-detailed-use-patch-sites]] .Uso Simplificado de `MASTER_SITES:n` com `PATCH_SITES` [example] ==== [.programlisting] .... PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test .... ==== [[port-master-sites-n-what-changed]] ==== O que Muda para os Ports? O que Não Funciona? [lowerroman] . Todos os ports atuais permanecem os mesmos. A feature `MASTER_SITES:n` só é ativada se houver elementos pós-fixados com `:__n__` como elementos de acordo com as regras de sintaxe acima, especialmente como mostrado no item <>. [[porting-master-sites-n-what-changes-in-port-targets]] . Os targets de port permanecem os mesmos: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. Com as exceções óbvias de `do-fetch`, `fetch-list`, `master-sites` e `patch-sites`. ** `do-fetch`: implementa o novo agrupamento pós-fixado `DISTFILES` e `PATCHFILES` com seus elementos de grupo correspondentes dentro de ambos `MASTER_SITES` e `PATCH_SITES` que usam elementos de grupo correspondentes dentro de ambos `MASTER_SITE_SUBDIR` e `PATCH_SITE_SUBDIR`. Verifique <>. ** `fetch-list`: funciona como o antigo `fetch-list`, com a exceção de que faz agrupamentos exatamente como o `do-fetch`. ** `master-sites` e `patch-sites`: (incompatível com versões mais antigas) somente retorna os elementos do grupo `DEFAULT`; na verdade, eles executam os targets `master-sites-default` e `patch-sites-default` respectivamente. + -Além disso, usar o target `master-sites-all` ou `patch-sites-all` é o preferido para verificar diretamente `MASTER_SITES` ou `PATCH_SITES`. Além disso, não é garantido que a checagem direta funcione em versões futuras. Veja <> para obter mais informações sobre esses novos tagets de port. +Além disso, usar o target `master-sites-all` ou `patch-sites-all` é o preferido para verificar diretamente `MASTER_SITES` ou `PATCH_SITES`. Além disso, não é garantido que a checagem direta funcione em versões futuras. Veja <> para obter mais informações sobre esses novos tagets de port. . Novos Targets de Port .. Existem targets `master-sites-_n_` e `patch-sites-_n_` que listarão os elementos do respectivo grupo _n_ dentro de `MASTER_SITES` e `PATCH_SITES` respectivamente. Por exemplo, ambos `master-sites-DEFAULT` e `patch-sites-DEFAULT` retornarão os elementos do grupo `DEFAULT`, `master-sites-test` e `patch-sites-test` do grupo `test`. [[porting-master-sites-n-new-port-targets-master-sites-all]] .. Há novos targets `master-sites-all` e `patch-sites-all` que fazem o trabalho dos antigos `master-sites` e `patch-sites`. Eles retornam os elementos de todos os grupos como se todos pertencessem ao mesmo grupo, com a ressalva de que lista tantos `MASTER_SITE_BACKUP` e `MASTER_SITE_OVERRIDE` como existem grupos definidos dentro de qualquer `DISTFILES` ou `PATCHFILES`; respectivamente para `master-sites-all` e `patch-sites-all`. [[makefile-dist_subdir]] === `DIST_SUBDIR` Não deixe o [.filename]#/usr/ports/distfiles# bagunçado. Se um port exigir que muitos arquivos sejam baixados, ou que contenha um arquivo que tenha um nome que possa entrar em conflito com outros ports (por exemplo, [.filename]#Makefile#), defina `DIST_SUBDIR` com o nome do port (`${PORTNAME}` ou `${PKGNAMEPREFIX}${PORTNAME}`). Isso vai mudar o `DISTDIR` do padrão [.filename]#/usr/ports/distfiles# para [.filename]#/usr/ports/distfiles/${DIST_SUBDIR}#,e assim, será colocado tudo o que é necessário para o port nesse subdiretório. Ele também examinará o subdiretório com o mesmo nome no site principal de backup em http://distcache.FreeBSD.org[http://distcache.FreeBSD.org] (Configurar o `DISTDIR` explicitamente no [.filename]#Makefile# não fará isso funcionar, então por favor use `DIST_SUBDIR`.) [NOTE] ==== Isso não afeta o `MASTER_SITES` definido no [.filename]#Makefile#. ==== [[makefile-maintainer]] == `MAINTAINER` Defina seu endereço de email aqui. Por favor. _:-)_ Apenas um único endereço sem a parte de comentário é permitido como um valor para `MAINTAINER`. O formato usado é `user@hostname.domain`. Por favor, não inclua nenhum texto descritivo, como um nome nesta entrada. Isso confunde a infraestrutura do Ports e a maioria das ferramentas que a usam. O mantenedor é responsável por manter o port atualizado e garantir que elo funcione corretamente. Para obter uma descrição detalhada das responsabilidades de um mantenedor de port, consulte extref:{contributing}[O desafio para os mantenedores de port, maintain-port]. [NOTE] ==== Um mantenedor se voluntaria para manter um port em bom estado de funcionamento. Os mantenedores têm a responsabilidade primária por seus ports, mas não possuem propriedade exclusiva. Os ports existem para o benefício da comunidade e, na realidade, pertencem à comunidade. O que isso significa é que outras pessoas além do mantenedor, também podem fazer alterações em um port. Grandes mudanças na Coleção de Ports podem exigir mudanças em muitos ports. A Equipe de Gerenciamento do Ports do FreeBSD ou membros de outras equipes podem modificar ports para corrigir problemas de dependência ou outros problemas, como um bump de versão para uma atualização de biblioteca compartilhada. Alguns tipos de correções tem "aprovação implícita" da Equipe de Gerenciamento do Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org], permitindo que qualquer committer conserte essas categorias de problemas em qualquer port. Essas correções não precisam da aprovação do mantenedor. Aprovação implícita para a maioria dos ports se aplicam para correções como mudanças de infraestrutura, trivialidades e correções _testadas_ de compilação e execução. A lista atual está disponibilizada em extref:{committers-guide}[Seção Ports do Guia dos Committers, ports-qa-misc-blanket-approval]. ==== Outras alterações no port serão enviadas ao mantenedor para revisão e aprovação antes de se fazer o commit. Se o mantenedor não responder a uma solicitação de atualização após duas semanas (excluindo os principais feriados), isso será considerado como timeout do mantenedor, e a atualização poderá ser feita sem a aprovação explícita do mesmo. Se o mantenedor não responder dentro de três meses, ou se houver três timeouts consecutivos, então o mantenedor é considerado ausente, e todas os seus ports podem ser atribuídos de volta para à comunidade. Exceções para isso são quaisquer ports mantidos pela Equipe de Gerenciamento de Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org] ou pela Equipe de Oficias de Segurança mailto:security-officer@FreeBSD.org[security-officer@FreeBSD.org]. Nenhum commit não autorizado pode ser feito em ports mantidos por esses grupos. Reservamo-nos o direito de modificar as submissões do mantenedor para melhor adequar as políticas e os estilos existentes da Coleção de Ports sem aprovação explicita do remetente ou do mantenedor. Além disso, grandes alterações de infraestrutura podem resultar na modificação de um port sem o consentimento do mantenedor. Estes tipos de alterações nunca irão afetar a funcionalidade do port. A Equipe de Gerenciamento de Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org] reserva o direito de revogar ou substituir a propriedade de mantenedor de qualquer pessoa por qualquer motivo, e a Equipe de Oficiais de Segurança mailto:security-officer@FreeBSD.org[security-officer@FreeBSD.org] reserva o direito de revogar ou substituir a propriedade de mantenedor por razões de segurança. [[makefile-comment]] == `COMMENT` O comentário é uma descrição de uma linha de um port mostrada por `pkg info`. Por favor, siga estas regras ao compor: . A string COMMENT deve ter 70 caracteres ou menos. . _Não_ inclua o nome do pacote ou o número da versão do software. . O comentário deve começar com uma letra maiúscula e terminar sem um ponto final. . Não comece com um artigo indefinido (isto é, A ou Um). . Capitalize nomes como Apache, JavaScript ou Perl. . Use uma vírgula serial para listas de palavras: "verde, vermelho, e azul." . Verifique erros de ortografia. Aqui está um exemplo: [.programlisting] .... COMMENT= Cat chasing a mouse all over the screen .... A variável COMMENT vem depois da variável MAINTAINER no [.filename]#Makefile#. [[licenses]] == Licenças Cada port deve documentar a licença sob a qual está disponível. Se não for uma licença aprovada pelo OSI, também deve documentar quaisquer restrições à redistribuição. [[licenses-license]] === `LICENSE` Um nome abreviado para a licença ou licenças se mais de uma licença for aplicada. Se for uma das licenças listadas no <>, apenas as variáveis `LICENSE_FILE` e `LICENSE_DISTFILES` podem ser definidas. Se esta for uma licença que não tenha sido definida na infraestrutura de ports (veja <>), `LICENSE_PERMS` e `LICENSE_NAME` devem ser definidos, juntamente com `LICENSE_FILE` ou `LICENSE_TEXT`. `LICENSE_DISTFILES` e `LICENSE_GROUPS` também podem ser definidos, mas não é necessário. As licenças pré-definidas são mostradas em <>. A lista atual está sempre disponível em [.filename]#Mk/bsd.licenses.db.mk#. [[licenses-license-ex1]] .Uso Mais Simples, Licenças Predefinidas [example] ==== Quando o [.filename]#README# de algum software diz "This software is under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version." mas não fornece o arquivo de licença, use isto: [.programlisting] .... LICENSE= LGPL21+ .... Quando o software fornece o arquivo de licença, use isto: [.programlisting] .... LICENSE= LGPL21+ LICENSE_FILE= ${WRKSRC}/COPYING .... ==== Para as licenças predefinidas, as permissões padrão são `dist-mirror dist-sell pkg-mirror pkg-sell auto-accept`. [[licenses-license-list]] .Lista de Licenças Predefinidas [cols="1,1,1,1", frame="none", options="header"] |=== | Nome Curto | Nome | Grupo | Permissões |`AGPLv3` |GNU Affero General Public License version 3 |`FSF GPL OSI` |(padrão) |`AGPLv3+` |GNU Affero General Public License version 3 (ou maior) |`FSF GPL OSI` |(padrão) |`APACHE10` |Apache License 1.0 |`FSF` |(padrão) |`APACHE11` |Apache License 1.1 |`FSF OSI` |(padrão) |`APACHE20` |Apache License 2.0 |`FSF OSI` |(padrão) |`ART10` |Artistic License version 1.0 |`OSI` |(padrão) |`ART20` |Artistic License version 2.0 |`FSF GPL OSI` |(padrão) |`ARTPERL10` |Artistic License (perl) version 1.0 |`OSI` |(padrão) |`BSD` |BSD license Generic Version (deprecated) |`FSF OSI COPYFREE` |(padrão) |`BSD2CLAUSE` |BSD 2-clause "Simplified" License |`FSF OSI COPYFREE` |(padrão) |`BSD3CLAUSE` |BSD 3-clause "New" or "Revised" License |`FSF OSI COPYFREE` |(padrão) |`BSD4CLAUSE` |BSD 4-clause "Original" or "Old" License |`FSF` |(padrão) |`BSL` |Boost Software License |`FSF OSI COPYFREE` |(padrão) |`CC-BY-1.0` |Creative Commons Attribution 1.0 | |(padrão) |`CC-BY-2.0` |Creative Commons Attribution 2.0 | |(padrão) |`CC-BY-2.5` |Creative Commons Attribution 2.5 | |(padrão) |`CC-BY-3.0` |Creative Commons Attribution 3.0 | |(padrão) |`CC-BY-4.0` |Creative Commons Attribution 4.0 | |(padrão) |`CC-BY-NC-1.0` |Creative Commons Attribution Non Commercial 1.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-2.0` |Creative Commons Attribution Non Commercial 2.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-2.5` |Creative Commons Attribution Non Commercial 2.5 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-3.0` |Creative Commons Attribution Non Commercial 3.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-4.0` |Creative Commons Attribution Non Commercial 4.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-ND-1.0` |Creative Commons Attribution Non Commercial No Derivatives 1.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-ND-2.0` |Creative Commons Attribution Non Commercial No Derivatives 2.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-ND-2.5` |Creative Commons Attribution Non Commercial No Derivatives 2.5 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-ND-3.0` |Creative Commons Attribution Non Commercial No Derivatives 3.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-ND-4.0` |Creative Commons Attribution Non Commercial No Derivatives 4.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-SA-1.0` |Creative Commons Attribution Non Commercial Share Alike 1.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-SA-2.0` |Creative Commons Attribution Non Commercial Share Alike 2.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-SA-2.5` |Creative Commons Attribution Non Commercial Share Alike 2.5 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-SA-3.0` |Creative Commons Attribution Non Commercial Share Alike 3.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-NC-SA-4.0` |Creative Commons Attribution Non Commercial Share Alike 4.0 | |`dist-mirror pkg-mirror auto-accept` |`CC-BY-ND-1.0` |Creative Commons Attribution No Derivatives 1.0 | |(padrão) |`CC-BY-ND-2.0` |Creative Commons Attribution No Derivatives 2.0 | |(padrão) |`CC-BY-ND-2.5` |Creative Commons Attribution No Derivatives 2.5 | |(padrão) |`CC-BY-ND-3.0` |Creative Commons Attribution No Derivatives 3.0 | |(padrão) |`CC-BY-ND-4.0` |Creative Commons Attribution No Derivatives 4.0 | |(padrão) |`CC-BY-SA-1.0` |Creative Commons Attribution Share Alike 1.0 | |(padrão) |`CC-BY-SA-2.0` |Creative Commons Attribution Compartilhar Alike 2.0 | |(padrão) |`CC-BY-SA-2.5` |Creative Commons Attribution Share Alike 2.5 | |(padrão) |`CC-BY-SA-3.0` |Creative Commons Attribution Share Alike 3.0 | |(padrão) |`CC-BY-SA-4.0` |Creative Commons Attribution Share Alike 4.0 | |(padrão) |`CC0-1.0` |Creative Commons Zero v1.0 Universal |`FSF GPL COPYFREE` |(padrão) |`CDDL` |Common Development and Distribution License |`FSF OSI` |(padrão) |`CPAL-1.0` |Common Public Attribution License |`FSF OSI` |(padrão) |`ClArtistic` |Clarified Artistic License |`FSF GPL OSI` |(padrão) |`EPL` |Eclipse Public License |`FSF OSI` |(padrão) |`GFDL` |GNU Free Documentation License |`FSF` |(padrão) |`GMGPL` |GNAT Modified General Public License |`FSF GPL OSI` |(padrão) |`GPLv1` |GNU General Public License version 1 |`FSF GPL OSI` |(padrão) |`GPLv1+` |GNU General Public License version 1 (or later) |`FSF GPL OSI` |(padrão) |`GPLv2` |GNU General Public License version 2 |`FSF GPL OSI` |(padrão) |`GPLv2+` |GNU General Public License version 2 (or later) |`FSF GPL OSI` |(padrão) |`GPLv3` |GNU General Public License version 3 |`FSF GPL OSI` |(padrão) |`GPLv3+` |GNU General Public License version 3 (or later) |`FSF GPL OSI` |(padrão) |`GPLv3RLE` |GNU GPL version 3 Runtime Library Exception |`FSF GPL OSI` |(padrão) |`GPLv3RLE+` |GNU GPL version 3 Runtime Library Exception (or later) |`FSF GPL OSI` |(padrão) |`ISCL` |Internet Systems Consortium License |`FSF GPL OSI COPYFREE` |(padrão) |`LGPL20` |GNU Library General Public License version 2.0 |`FSF GPL OSI` |(padrão) |`LGPL20+` |GNU Library General Public License version 2.0 (or later) |`FSF GPL OSI` |(padrão) |`LGPL21` |GNU Lesser General Public License version 2.1 |`FSF GPL OSI` |(padrão) |`LGPL21+` |GNU Lesser General Public License version 2.1 (or later) |`FSF GPL OSI` |(padrão) |`LGPL3` |GNU Lesser General Public License version 3 |`FSF GPL OSI` |(padrão) |`LGPL3+` |GNU Lesser General Public License version 3 (or later) |`FSF GPL OSI` |(padrão) |`LPPL10` |LaTeX Project Public License version 1.0 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL11` |LaTeX Project Public License version 1.1 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL12` |LaTeX Project Public License version 1.2 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13` |LaTeX Project Public License version 1.3 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13a` |LaTeX Project Public License version 1.3a |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13b` |LaTeX Project Public License version 1.3b |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13c` |LaTeX Project Public License version 1.3c |`FSF OSI` |`dist-mirror dist-sell` |`MIT` |MIT license / X11 license |`COPYFREE FSF GPL OSI` |(padrão) |`MPL10` |Mozilla Public License version 1.0 |`FSF OSI` |(padrão) |`MPL11` |Mozilla Public License version 1.1 |`FSF OSI` |(padrão) |`MPL20` |Mozilla Public License version 2.0 |`FSF OSI` |(padrão) |`NCSA` |University of Illinois/NCSA Open Source License |`COPYFREE FSF GPL OSI` |(padrão) |`NONE` |No license specified | |`none` |`OFL10` |SIL Open Font License version 1.0 (http://scripts.sil.org/OFL) |`FONTS` |(padrão) |`OFL11` |SIL Open Font License version 1.1 (http://scripts.sil.org/OFL) |`FONTS` |(padrão) |`OWL` |Open Works License (owl.apotheon.org) |`COPYFREE` |(padrão) |`OpenSSL` |Licença OpenSSL |`FSF` |(padrão) |`PD` |Public Domain |`GPL COPYFREE` |(padrão) |`PHP202` |PHP License version 2.02 |`FSF OSI` |(padrão) |`PHP30` |PHP License version 3.0 |`FSF OSI` |(padrão) |`PHP301` |PHP License versão 3.01 |`FSF OSI` |(padrão) |`PSFL` |Python Software Foundation License |`FSF GPL OSI` |(padrão) |`PostgreSQL` |PostgreSQL License |`FSF GPL OSI COPYFREE` |(padrão) |`RUBY` |Ruby License |`FSF` |(padrão) |`UNLICENSE` |The Unlicense |`COPYFREE FSF GPL` |(padrão) |`WTFPL` |Do What the Fuck You Want To Public License version 2 |`GPL FSF COPYFREE` |(padrão) |`WTFPL1` |Do What the Fuck You Want To Public License version 1 |`GPL FSF COPYFREE` |(padrão) |`ZLIB` |zlib License |`GPL FSF OSI` |(padrão) |`ZPL21` |Zope Public License version 2.1 |`GPL OSI` |(padrão) |=== [[licenses-license_perms]] === `LICENSE_PERMS` e `LICENSE_PERMS_NAME` Permissões. Use `none` se vazio. .Lista de Permissões de Licença [[licenses-license_perms-dist-mirror]] `dist-mirror`:: A redistribuição dos arquivos de distribuição é permitida. Os arquivos de distribuição serão adicionados ao FreeBSD CDN `MASTER_SITE_BACKUP`. [[licenses-license_perms-no-dist-mirror]] `no-dist-mirror`:: A redistribuição dos arquivos de distribuição é proibida. Isso é equivalente a <>. Os arquivos de distribuição _não_ serão adicionados ao FreeBSD CDN `MASTER_SITE_BACKUP`. [[licenses-license_perms-dist-sell]] `dist-sell`:: A venda de arquivos de distribuição é permitida. Os arquivos de distribuição estarão presentes nas imagens do instalador. [[licenses-license_perms-no-dist-sell]] `no-dist-sell`:: A venda de arquivos de distribuição é proibida. Isso é equivalente a <>. [[licenses-license_perms-pkg-mirror]] `pkg-mirror`:: É permitida a redistribuição gratuita do pacote. O pacote será distribuído na CDN de pacotes do FreeBSD https://pkg.freebsd.org/[https://pkg.freebsd.org/]. [[licenses-license_perms-no-pkg-mirror]] `no-pkg-mirror`:: É proibida a redistribuição gratuita do pacote. Equivalente à definir <>. O pacote _não_ será distribuído a partir da CDN de pacotes do FreeBSD https://pkg.freebsd.org/[https://pkg.freebsd.org/]. [[licenses-license_perms-pkg-sell]] `pkg-sell`:: A venda do pacote é permitida. O pacote estará presente nas imagens do instalador. [[licenses-license_perms-no-pkg-sell]] `no-pkg-sell`:: A venda de pacotes é proibida. Isso é equivalente a definir <>. O pacote _não_ estará presente nas imagens do instalador. [[licenses-license_perms-auto-accept]] `auto-accept`:: A licença é aceita por padrão. Os prompts para aceitar uma licença não são exibidos a menos que o usuário tenha definido `LICENSES_ASK`. Use isto, a menos que a licença indique que o usuário deve aceitar os termos da licença. [[licenses-license_perms-no-auto-accept]] `no-auto-accept`:: A licença não é aceita por padrão. O usuário sempre será solicitado a confirmar a aceitação desta licença. Isso deve ser usado se a licença declarar que o usuário deve aceitar seus termos. Quando ambos `_permission_` e `no-_permission_` estiverem presentes o `no-_permission_` vai cancelar a `_permission_`. Quando `_permission_` não estiver presente, é considerado uma `no-_permission_`. [WARNING] ==== Algumas permissões que estiverem faltando, impedirão que um port (e todos os ports dependendo dele) sejam utilizados pelos usuários do pacote: Um port sem a permissão `auto-accept` nunca será compilado e todos os ports dependendo dele serão ignorados. Um port sem a permissão `pkg-mirror` será removido, assim como todos os ports que dependam dele, isso depois da compilação e então eles nunca serão distribuídos. ==== [[licenses-license_perms-ex1]] .Licença Não Padrão [example] ==== Leia os termos da licença e traduza-os usando as permissões disponíveis. [.programlisting] .... LICENSE= UNKNOWN LICENSE_NAME= unknown LICENSE_TEXT= Esse programa NÃO é de domínio publico.\ pode ser distribuído livremente para propósitos não comerciais apenas,\ e NÃO HÁ GARANTIA PARA ESSE PROGRAMA. LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept .... ==== [[licenses-license_perms-ex2]] .Licenças Padrão e Não Padrão [example] ==== Leia os termos da licença e expresse-os usando as permissões disponíveis. Em caso de dúvida, peça orientação na http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[lista de discussão de ports do FreeBSD]. [.programlisting] .... LICENSE= WARSOW GPLv2 LICENSE_COMB= multi LICENSE_NAME_WARSOW= Warsow Content License LICENSE_FILE_WARSOW= ${WRKSRC}/docs/license.txt LICENSE_PERMS_WARSOW= dist-mirror pkg-mirror auto-accept .... Quando as permissões das licenças GPLv2 e UNKNOWN são misturadas, o port termina com `dist-mirror dist-sell pkg-mirror pkg-sell auto-accept dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept`. O `no-_permissions_` cancela as _permissions_. A lista resultante de permissões é _dist-mirror pkg-mirror auto-accept_. Os arquivos de distribuição e os pacotes não estarão disponíveis nas imagens do instalador. ==== [[licenses-license_groups]] === `LICENSE_GROUPS` e `LICENSE_GROUPS_NAME` Grupos que a licença pertence. .Lista de Grupos de Licenças Predefinidas [[licenses-license_groups-FSF]] `FSF`:: Aprovada pela Free Software Foundation, veja http://www.fsf.org/licensing[FSF Licensing & Compliance Team]. [[licenses-license_groups-GPL]] `GPL`:: Compatível com GPL [[licenses-license_groups-OSI]] `OSI`:: Aprovado pelo OSI, veja a pagina Open Source Initiative http://opensource.org/licenses[Open Source Licenses]. [[licenses-license_groups-COPYFREE]] `COPYFREE`:: Segue a Copyfree Standard Definition, consulte a pagina http://copyfree.org/standard/licenses[Copyfree Licenses]. [[licenses-license_groups-FONTS]] `FONTS`:: Licenças de fonte [[licenses-license_name]] === `LICENSE_NAME` e `LICENSE_NAME_NAME` Nome completo da licença. [[licenses-license_name-ex1]] .`LICENSE_NAME` [example] ==== [.programlisting] .... LICENSE= UNRAR LICENSE_NAME= UnRAR License LICENSE_FILE= ${WRKSRC}/license.txt LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept .... ==== [[licenses-license_file]] === `LICENSE_FILE` e `LICENSE_FILE_NOME` Caminho completo para o arquivo que contém o texto da licença, geralmente [.filename]#${WRKSRC}/some/file#. Se o arquivo não estiver no distfile e seu conteúdo for muito longo para ser colocado em <>, insira o texto em um novo arquivo em [.filename]#${FILESDIR}#. [[licenses-license_file-ex1]] .`LICENSE_FILE` [example] ==== [.programlisting] .... LICENSE= GPLv3+ LICENSE_FILE= ${WRKSRC}/COPYING .... ==== [[licenses-license_text]] === `LICENSE_TEXT` e `LICENSE_TEXT_NAME` Texto para usar como uma licença. Útil quando a licença não está nos arquivos de distribuição e seu texto é curto. [[licenses-license_text-ex1]] .`LICENSE_TEXT` [example] ==== [.programlisting] .... LICENSE= UNKNOWN LICENSE_NAME= unknown LICENSE_TEXT= This program is NOT in public domain.\ It can be freely distributed for non-commercial purposes only,\ and THERE IS NO WARRANTY FOR THIS PROGRAM. LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept .... ==== [[licenses-license_distfiles]] === `LICENSE_DISTFILES` e `LICENSE_DISTFILES_NAME` Os arquivos de distribuição aos quais as licenças se aplicam. O padrão é para todos os arquivos de distribuição. [[licenses-license_distfiles-ex1]] .`LICENSE_DISTFILES` [example] ==== Usado quando os arquivos de distribuição não possuem a mesma licença. Por exemplo, um possui uma licença de código e outro possui alguns trabalhos de arte que não podem ser redistribuídos: [.programlisting] .... MASTER_SITES= SF/some-game DISTFILES= ${DISTNAME}${EXTRACT_SUFX} artwork.zip LICENSE= BSD3CLAUSE ARTWORK LICENSE_COMB= dual LICENSE_NAME_ARTWORK= The game artwork license LICENSE_TEXT_ARTWORK= The README says that the files cannot be redistributed LICENSE_PERMS_ARTWORK= pkg-mirror pkg-sell auto-accept LICENSE_DISTFILES_BSD3CLAUSE= ${DISTNAME}${EXTRACT_SUFX} LICENSE_DISTFILES_ARTWORK= artwork.zip .... ==== [[licenses-license_comb]] === `LICENSE_COMB` Defina como `multi` se todas as licenças se aplicarem. Defina como `dual` se qualquer uma das licenças se aplica. O padrão é definido para `single`. [[licenses-license_comb-ex1]] .Licenças Duplas [example] ==== Quando um port diz "This software may be distributed under the GNU General Public License or the Artistic License">, isso significa que qualquer licença pode ser usada. Use isto: [.programlisting] .... LICENSE= ART10 GPLv1 LICENSE_COMB= dual .... Se os arquivos de licença forem fornecidos, use assim: [.programlisting] .... LICENSE= ART10 GPLv1 LICENSE_COMB= dual LICENSE_FILE_ART10= ${WRKSRC}/Artistic LICENSE_FILE_GPLv1= ${WRKSRC}/Copying .... ==== [[licenses-license_comb-ex2]] .Múltiplas Licenças [example] ==== Quando parte de um port tem uma licença, e outra parte tem uma licença diferente, use `multi`: [.programlisting] .... LICENSE= GPLv2 LGPL21+ LICENSE_COMB= multi .... ==== [[makefile-portscout]] == `PORTSCOUT` -Portscout é um utilitário de verificação de distfile automatizado para a Coleção de Ports do FreeBSD, descrito em detalhes em <>. +Portscout é um utilitário de verificação de distfile automatizado para a Coleção de Ports do FreeBSD, descrito em detalhes em crossref:keeping-up[distfile-survey,Portscout: o Scanner de Distfile de Ports do FreeBSD]. `PORTSCOUT` define condições especiais dentro das quais o scanner distfile do Portscout é restrito. Situações em que o `PORTSCOUT` é configurado: * Quando distfiles precisam ser ignorados, seja para versões específicas, ou para pequenas revisões específicas. Por exemplo, para excluir a versão _8.2_ das verificações de versão de distfile porque é conhecido por estar quebrado, adicione: + [.programlisting] .... PORTSCOUT= ignore:8.2 .... * Quando versões específicas ou revisões maiores e menores específicas de um distfile devem ser verificadas. Por exemplo, se somente a versão _0.6.4_ deve ser monitorado porque versões mais recentes têm problemas de compatibilidade com o FreeBSD, adicione: + [.programlisting] .... PORTSCOUT= limit:^0\.6\.4 .... * Quando os URLs que listam as versões disponíveis diferem dos URLs de download. Por exemplo, para limitar as verificações de versão do arquivo distfile à página de download para o port package:databases/pgtune[], adicione: + [.programlisting] .... PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416 .... [[makefile-depend]] == Dependências Muitos ports dependem de outros ports. Esta é uma característica muito conveniente da maioria dos sistemas operacionais Unix-like, incluindo FreeBSD. Vários ports podem compartilhar uma dependência comum, ao invés de agrupar essa dependência com cada port ou pacote que precisa dela. Há sete variáveis ​​que podem ser usadas para garantir que todos os bits necessários estejam na máquina do usuário. Existem também algumas variáveis ​​de dependência pré-suportadas para casos comuns, além de algumas outras para controlar o comportamento das dependências. [IMPORTANT] ==== Quando o software possui dependências extras que fornecem recursos extras, as dependências básicas listadas em `*_DEPENDS` devem incluir as dependências extras que beneficiariam a maioria dos usuários. As dependências básicas nunca devem ser um conjunto de dependências "mínima". O objetivo não é incluir todas as dependências possíveis. Inclua apenas aquelas que beneficiarão a maioria das pessoas. ==== [[makefile-lib_depends]] === `LIB_DEPENDS` Esta variável especifica as bibliotecas compartilhadas das quais este port depende. É uma lista de tuplas _lib:dir_ onde _lib_ é o nome da biblioteca compartilhada, _dir_ é o diretório no qual encontrá-lo, caso não esteja disponível. Por exemplo, [.programlisting] .... LIB_DEPENDS= libjpeg.so:graphics/jpeg .... irá verificar se há uma biblioteca jpeg compartilhada com qualquer versão no subdiretório [.filename]#graphics/jpeg# da árvore de ports para compilar e instalar se não for encontrado. A dependência é verificada duas vezes, uma vez dentro do target `build` e depois dentro do target `install`. Além disso, o nome da dependência é colocado no pacote para que o `pkg-install` (veja man:pkg-install[8]) a instale automaticamente se a mesma não estiver no sistema do usuário. [[makefile-run_depends]] === `RUN_DEPENDS` Esta variável especifica arquivos executáveis ou arquivos para os quais este port depende durante o tempo de execução. É uma lista de tuplas path:dir:[``target``] onde _path_ é o nome do executável ou arquivo,_dir_ é o diretório no qual encontrá-lo, caso não esteja disponível, e o _target_ é o target para chamar nesse diretório. E se o _path_ começar com uma barra (`/`), ele será tratado como um arquivo e sua existência é testada com `test -e`; caso contrário, é assumido como um executável e `which -s` é usado para determinar se o programa existe no caminho de pesquisa. Por exemplo, [.programlisting] .... RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:news/inn \ xmlcatmgr:textproc/xmlcatmgr .... irá verificar se o arquivo ou diretório [.filename]#/usr/local/news/bin/innd# existe, e compilar e instalá-lo a partir do subdiretório [.filename]#news/inn# da árvore de ports, caso não seja encontrado. Ele também verá se um executável chamado `xmlcatmgr` está no caminho de pesquisa em [.filename]#textproc/xmlcatmgr# para compilar e instalar se não for encontrado. [NOTE] ==== Nesse caso, `innd` é na verdade um executável; se um executável estiver em um local que não deve estar no caminho de pesquisa, use o nome do caminho completo. ==== [NOTE] ==== A pesquisa oficial `PATH` usado no cluster de construção de ports é [.programlisting] .... /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .... ==== A dependência é verificada a partir do target `install`. Além disso, o nome da dependência é colocado no pacote para que o `pkg-install` (veja man:pkg-install[8]) a instale automaticamente se a mesma não estiver no sistema do usuário. A parte _target_ pode ser omitida se for igual a `DEPENDS_TARGET`. Uma situação bastante comum é quando `RUN_DEPENDS` é literalmente o mesmo que `BUILD_DEPENDS`, especialmente se o software portado é escrito em uma linguagem de script ou se requer o mesmo ambiente de compilação e tempo de execução. Neste caso, é tentador e intuitivo atribuir diretamente um ao outro: [.programlisting] .... RUN_DEPENDS= ${BUILD_DEPENDS} .... No entanto, essa atribuição pode poluir as dependências de tempo de execução com entradas não definidas no `BUILD_DEPENDS` original do port. Isso acontece por causa de uma avaliação preguiçosa de atribuição de variáveis do man:make[1]. Considere um [.filename]#Makefile# com `USES_*`, que são processados ​​por [.filename]#ports/Mk/bsd.*.mk# para aumentar as dependências iniciais de compilação. Por exemplo, `USES=gmake` adiciona package:devel/gmake[] para `BUILD_DEPENDS`. Para evitar que essas dependências adicionais poluam `RUN_DEPENDS`, crie outra variável com o conteúdo atual de `BUILD_DEPENDS` e atribua-a para ambos `BUILD_DEPENDS` e `RUN_DEPENDS`: [.programlisting] .... MY_DEPENDS= some:devel/some \ other:lang/other BUILD_DEPENDS= ${MY_DEPENDS} RUN_DEPENDS= ${MY_DEPENDS} .... [IMPORTANT] ==== _Não_ use `:=` para atribuir `BUILD_DEPENDS` para `RUN_DEPENDS` ou vice-versa. Todas as variáveis ​​são expandidas imediatamente, o que é exatamente a coisa errada a fazer e quase sempre um fracasso. ==== [[makefile-build_depends]] === `BUILD_DEPENDS` Esta variável especifica executáveis ​​ou arquivos que este port requer para ser compilado. Como `RUN_DEPENDS`, ela é uma lista de tuplas path:dir:[``target``]. Por exemplo, [.programlisting] .... BUILD_DEPENDS= unzip:archivers/unzip .... irá procurar por um executável chamado `unzip`, e ir para o subdiretório [.filename]#archivers/unzip# da árvore de ports para compilar e instalar se não for encontrado. [NOTE] ==== "build" aqui significa tudo, desde a extração até a compilação. A dependência é verificada a partir do target `extract`. A parte do _target_ pode ser omitida se for igual a `DEPENDS_TARGET` ==== [[makefile-fetch_depends]] === `FETCH_DEPENDS` Esta variável especifica executáveis ​​ou arquivos que este port requer para fazer os downloads. Como os dois anteriores, é uma lista de tuplas path:dir:[``target``]. Por exemplo, [.programlisting] .... FETCH_DEPENDS= ncftp2:net/ncftp2 .... irá procurar por um executável chamado `ncftp2` e ir para o subdiretório [.filename]#net/ncftp2# da árvore de ports para compilar e instalar se não for encontrado. A dependência é verificada a partir do target `fetch`. A parte _target_ pode ser omitida se for igual a `DEPENDS_TARGET`. [[makefile-extract_depends]] === `EXTRACT_DEPENDS` Esta variável especifica executáveis ​​ou arquivos que este port requer para extração. Como no anterior, é uma lista de tuplas path:dir:[``target``]. Por exemplo, [.programlisting] .... EXTRACT_DEPENDS= unzip:archivers/unzip .... irá procurar por um executável chamado `unzip`, e ir para o subdiretório [.filename]#archivers/unzip# da árvore de ports para compilar e instalar se não for encontrado. A dependência é verificada a partir do target `extract`. A parte _target_ pode ser omitida se for igual a `DEPENDS_TARGET`. [NOTE] ==== -Use esta variável somente se a extração ainda não funcionar (o padrão usa `tar`) e não funciona com `USES=tar`, `USES=lha` ou `USES=zip` descrito em <>. +Use esta variável somente se a extração ainda não funcionar (o padrão usa `tar`) e não funciona com `USES=tar`, `USES=lha` ou `USES=zip` descrito em crossref:uses[uses,Usando Macros `USES`]. ==== [[makefile-patch_depends]] === `PATCH_DEPENDS` Esta variável especifica executáveis ​​ou arquivos que este port requer para aplicar patches. Como no anterior, é uma lista de path:dir:[``target``]. Por exemplo, [.programlisting] .... PATCH_DEPENDS= ${NONEXISTENT}:java/jfc:extract .... vai descer para o subdiretório [.filename]#java/jfc# da árvore de ports para extraí-lo. A dependência é verificada a partir do target `patch`. A parte _target_ pode ser omitida se for igual a `DEPENDS_TARGET`. [[makefile-uses]] === `USES` Parâmetros podem ser adicionados para definir diferentes recursos e dependências usados ​​pelo port. Eles são especificados adicionando esta linha ao [.filename]#Makefile#: [.programlisting] .... USES= feature[:arguments] .... -Para a lista completa de valores, por favor veja o <>. +Para a lista completa de valores, por favor veja o crossref:uses[uses,Usando Macros `USES`]. [WARNING] ==== `USES` não pode ser atribuído após a inclusão de [.filename]#bsd.port.pre.mk#. ==== [[makefile-use-vars]] == 0 `USE_*` Diversas variáveis ​​existem para definir dependências comuns compartilhadas por muitos ports. O uso é opcional, mas ajuda a reduzir a verbosidade dos [.filename]##Makefile##s de port . Cada um deles é denominado como `USES_*`. Essas variáveis ​​podem ser usadas apenas no [.filename]#Makefile# do port e [.filename]#ports/Mk/bsd.*.mk#. Elas não são destinadas a opções configuráveis ​​pelo usuário - use `PORT_OPTIONS` para esse propósito. [NOTE] ==== É _sempre_ incorreto definir qualquer `USE_*` dentro de [.filename]#/etc/make.conf#. Por exemplo, definindo [.programlisting] .... USE_GCC=X.Y .... (onde XY é o número da versão) adicionaria uma dependência do gccXY para cada port, incluindo `lang/gccXY` em si! ==== [[makefile-use-vars-table]] .`USE_*` [cols="1,1", frame="none", options="header"] |=== | Variável | Significa |`USE_GCC` a| O port requer GCC (gcc ou {gcc-plus-plus}) para compilar. Alguns ports precisam de qualquer versão do GCC, algumas exigem versões modernas e recentes. Normalmente, é configurado para `qualquer` (neste caso, o GCC da base seria usado em versões do FreeBSD que ainda o possuem, ou o port `lang/gcc` seria instalado quando o compilador C/C++ padrão for o Clang); ou `yes` (significa usar sempre GCC estável e moderno do port `lang/gcc`). A versão exata também pode ser especificada, com um valor como `4.7`. A versão mínima exigida pode ser especificada como `4.6+`. O GCC do sistema base é usado quando satisfaz a versão solicitada, caso contrário, um compilador apropriado é compilado a partir do port, e `CC` e `CXX` são ajustados em conformidade. [NOTE] ==== `USE_GCC` irá registrar uma dependência de tempo de compilação e uma de tempo de execução. ==== |=== -Variáveis ​​relacionadas ao gmake e [.filename]#configure# são descritos em <>, enquanto autoconf, automake e libtool são descritos em <>. Variáveis relacionadas ao Perl ​são descritas em <>. Variáveis ​​X11 são listadas em <>. <> lida com o GNOME e <> com variáveis ​​relacionadas ao KDE. <> documenta variáveis ​​Java, enquanto <> contém informações sobre Apache, PHP e módulos PEAR. Python é discutido em <>, e Ruby em <>. <> fornece variáveis ​​usadas para aplicações SDL e, finalmente, <> contém informações sobre o Xfce. +Variáveis ​​relacionadas ao gmake e [.filename]#configure# são descritos em crossref:special[building, Mecanismos de Compilação], enquanto autoconf, automake e libtool são descritos em crossref:special[using-autotools, Usando o GNU Autotools]. Variáveis relacionadas ao Perl ​são descritas em crossref:special[using-perl, Usando Perl]. Variáveis ​​X11 são listadas em crossref:special[using-x11, Usando o X11]. crossref:special[using-gnome, Usando o GNOME] lida com o GNOME e crossref:special[using-kde, Usando o KDE] com variáveis ​​relacionadas ao KDE. crossref:special[using-java, Usando Java] documenta variáveis ​​Java, enquanto crossref:special[using-php, Aplicações Web, Apache e PHP] contém informações sobre Apache, PHP e módulos PEAR. Python é discutido em crossref:special[using-python, Usando Python], e Ruby em crossref:special[using-ruby, Usando Ruby]. crossref:special[using-sdl, Usando SDL] fornece variáveis ​​usadas para aplicações SDL e, finalmente, crossref:special[using-xfce, Usando o Xfce] contém informações sobre o Xfce. [[makefile-version-dependency]] === Versão Mínima de uma Dependência Uma versão mínima de uma dependência pode ser especificada em qualquer `*_DEPENDS`, exceto `LIB_DEPENDS`, usando esta sintaxe: [.programlisting] .... p5-Spiffy>=0.26:devel/p5-Spiffy .... O primeiro campo contém um nome de pacote dependente, que deve corresponder à entrada no banco de dados de pacotes, um sinal de comparação e uma versão do pacote. A dependência é satisfeita se o p5-Spiffy-0.26 ou mais recente estiver instalado na máquina. [[makefile-note-on-dependencies]] === Notas sobre Dependências Como mencionado acima, o target padrão para chamar quando uma dependência é necessária é o `DEPENDS_TARGET`. Seu padrão é o `install`. Esta é uma variável de usuário; nunca é definido em um [.filename]#Makefile# de port. Se o port precisar de uma maneira especial de lidar com uma dependência, use a parte `:target` de `*_DEPENDS` em vez de redefinir `DEPENDS_TARGET`. Quando rodar `make clean`, as dependências de port também são limpas automaticamente. Se isso não for desejável, defina `NOCLEANDEPENDS` no ambiente. Isto pode ser particularmente desejável se o port tiver algo que demore muito tempo para recompilar em sua lista de dependências, como o KDE, o GNOME ou o Mozilla. Para depender de outro port incondicionalmente, use a variável `${NONEXISTENT}` no primeiro campo do `BUILD_DEPENDS` ou `RUN_DEPENDS`. Use isto somente quando o código fonte do outro port for necessário. Tempo de compilação pode ser economizado especificando o target também. Por exemplo [.programlisting] .... BUILD_DEPENDS= ${NONEXISTENT}:graphics/jpeg:extract .... sempre descerá para o port `jpeg` e extrai-lo. [[makefile-circular-dependencies]] === Dependências Circulares são Fatais [IMPORTANT] ==== Não insira nenhuma dependência circular na árvore de ports! ==== A tecnologia de compilação de ports não tolera dependências circulares. Se uma for inserida, alguém, em algum lugar do mundo, terá sua instalação do FreeBSD quebrada quase que imediatamente, e muitos outros rapidamente terão o mesmo problema. Estes erros podem ser realmente difíceis de serem detectados. Em caso de dúvida, antes de fazer qualquer alteração, certifique-se de executar: `cd /usr/ports; make index`. Esse processo pode ser muito lento em máquinas mais antigas, mas pode evitar dor de cabeça para um grande número de pessoas, incluindo você. [[makefile-automatic-dependencies]] === Problemas Causados ​​por Dependências Automáticas Dependências devem ser declaradas explicitamente ou usando o <>. Usar outros métodos, como a detecção automática, dificulta a indexação, o que causa problemas para o gerenciamento de ports e pacotes. [[makefile-automatic-dependencies-bad]] .Declaração Errada de uma Dependência Opcional [example] ==== [.programlisting] .... .include .if exists(${LOCALBASE}/bin/foo) LIB_DEPENDS= libbar.so:foo/bar .endif .... ==== O problema em tentar adicionar dependências automaticamente é que os arquivos e configurações fora de um port individual podem ser alterados a qualquer momento. Por exemplo: um índice é construído, depois um lote de ports é instalado. Mas um dos ports instala o arquivo testado. O índice então fica incorreto, porque um port instalado inesperadamente tem uma nova dependência. O índice ainda pode estar errado mesmo após a recriação, se outros ports também determinarem a necessidade de dependências com base na existência de outros arquivos. [[makefile-automatic-dependencies-good]] .Declaração Correta de uma Dependência Opcional [example] ==== [.programlisting] .... OPTIONS_DEFINE= BAR BAR_DESC= Calling cellphones via bar BAR_LIB_DEPENDS= libbar.so:foo/bar .... ==== Testar variáveis ​​de opções é o método correto. Ele não causará inconsistências no índice de um lote de ports, desde que as opções tenham sido definidas antes da construção do índice. Scripts simples podem ser usados ​​para automatizar a compilação, instalação e atualização desses ports e seus pacotes. [[makefile-masterdir]] == Ports Slaves e `MASTERDIR` Se o port precisar criar versões ligeiramente diferentes de pacotes fazendo com que uma variável (por exemplo, resolução ou tamanho de papel) assuma valores diferentes, crie um subdiretório por pacote para facilitar aos usuários a visualização do que fazer, mas tente compartilhar o máximo possível de arquivos entre os ports. Normalmente, usando variáveis ​​inteligentemente, apenas um [.filename]#Makefile# bem curto será necessário em todos, exceto em um dos diretórios. No [.filename]#Makefile# solitário, use `MASTERDIR` para especificar o diretório onde o restante dos arquivos estão. Além disso, use uma variável como parte de <> para que os pacotes tenham nomes diferentes. Isso será melhor demonstrado por um exemplo. Isso é parte de [.filename]#print/pkfonts300/Makefile#; [.programlisting] .... PORTNAME= pkfonts${RESOLUTION} PORTVERSION= 1.0 DISTFILES= pk${RESOLUTION}.tar.gz PLIST= ${PKGDIR}/pkg-plist.${RESOLUTION} .if !defined(RESOLUTION) RESOLUTION= 300 .else .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 360 && \ ${RESOLUTION} != 400 && ${RESOLUTION} != 600 .BEGIN: @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO_MSG} "Possible values are: 118, 240, 300, 360, 400 and 600." @${FALSE} .endif .endif .... package:print/pkfonts300[] também tem todos os patches, arquivos de pacotes, etc. Rodando `make` nele, será assumido o valor padrão para a resolução (300) e o port será compilado normalmente. Quanto às outras resoluções, este é o [.filename]#print/pkfonts360/Makefile#_completo_: [.programlisting] .... RESOLUTION= 360 MASTERDIR= ${.CURDIR}/../pkfonts300 .include "${MASTERDIR}/Makefile" .... ([.filename]#print/pkfonts118/Makefile#, [.filename]#print/pkfonts600/Makefile#, e todos os outros são semelhantes). A definição de `MASTERDIR` diz ao [.filename]#bsd.port.mk# que o conjunto regular de subdiretórios como `FILESDIR` e `SCRIPTDIR` podem ser encontrados em [.filename]#pkfonts300#. A linha `RESOLUTION=360` irá substituir a linha `RESOLUTION=300` em [.filename]#pkfonts300/Makefile# e o port será compilado com a resolução definida para 360. [[makefile-manpages]] == Páginas de Manual Se o port instala a sua árvore de manuais em outro lugar diferente de `PREFIX`, use `MANDIRS` para especificar esses diretórios. Note que os arquivos correspondentes às páginas de manual devem ser colocados no [.filename]#pkg-plist# junto com o resto dos arquivos. O propósito do `MANDIRS` é ativar a compactação automática de páginas de manual, portanto, os nomes dos arquivos são sufixados com [.filename]#.gz#. [[makefile-info]] == Arquivos de Informação Se o pacote precisar instalar arquivos de informações GNU, liste-os na variável `INFO` (sem o sufixo `.info`), uma entrada por documento. Presume-se que esses arquivos estejam instalados em [.filename]#PREFIX/INFO_PATH#. Mude `INFO_PATH` se o pacote usa um local diferente. Contudo, isto não é recomendado. Essas entradas contêm apenas o caminho relativo para [.filename]#PREFIX/INFO_PATH#. Por exemplo, package:lang/gcc34[] instala arquivos de informações em [.filename]#PREFIX/INFO_PATH/gcc34# e `INFO` será algo assim: [.programlisting] .... INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ... .... O código apropriado de instalação/desinstalação será automaticamente adicionado ao arquivo [.filename]#pkg-plist# temporário antes do registro do pacote. [[makefile-options]] == Opções do Makefile Muitas aplicações podem ser compiladas com configurações opcionais ou diferentes. Exemplos podem ser a escolha de linguagem natural (humana), GUI versus linha de comando ou qual tipo de banco de dados será suportado. Os usuários podem precisar de uma configuração diferente do padrão, portanto o sistema de ports fornece ganchos em que o autor do port pode usar para controlar qual variante será compilada. Suportar essas opções corretamente fará com que os usuários fiquem felizes, e efetivamente forneça dois ou mais ports pelo preço de um. [[makefile-options-options]] === `OPTIONS` [[makefile-options-background]] ==== Background `OPTIONS_*` fornece ao usuário que está instalando o port uma caixa de diálogo mostrando as opções disponíveis e, em seguida, salva essas opções em [.filename]#${PORT_DBDIR}/${OPTIONS_NAME}/options#. Na próxima vez que o port for compilado, as opções serão reutilizadas. O padrão de `PORT_DBDIR` é [.filename]#/var/db/ports#. `OPTIONS_NAME` é a origem do port com um underline como o separador de espaço, por exemplo, package:dns/bind99[] será `dns_bind99`. Quando o usuário executa `make config` (ou executa `make build` pela primeira vez), o framework verifica [.filename]#${PORT_DBDIR}/${OPTIONS_NAME}/options#. Se esse arquivo não existir, os valores de `OPTIONS_*` são usados ​​e uma caixa de diálogo é exibida onde as opções podem ser ativadas ou desativadas. Então as [.filename]#options# são salvas e as variáveis ​​configuradas são utilizadas ao compilar o port. Se uma nova versão do port adicionar novas `OPTIONS`, a caixa de diálogo será apresentada ao usuário, já preenchido com os valores salvos das antigas `OPTIONS`. `make showconfig` mostra a configuração salva. Use `make rmconfig` para remover a configuração salva. [[makefile-options-syntax]] ==== Sintaxe `OPTIONS_DEFINE` contém uma lista de `OPTIONS` para serem utilizadas. Elas são independentes umas das outras e não são agrupadas: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .... Uma vez definido, as `OPTIONS` são descritas (opcionalmente, mas fortemente recomendado): [.programlisting] .... OPT1_DESC= Describe OPT1 OPT2_DESC= Describe OPT2 OPT3_DESC= Describe OPT3 OPT4_DESC= Describe OPT4 OPT5_DESC= Describe OPT5 OPT6_DESC= Describe OPT6 .... [.filename]#ports/Mk/bsd.options.desc.mk# possui descrições para muitas `OPTIONS` comuns. Geralmente são úteis, mas podem ser substituas se a descrição for insuficiente para o port. [TIP] ==== Ao descrever as opções, visualize-as da perspectiva do usuário: "Qual funcionalidade ela muda?" e "Por que eu iria querer habilitar ela?" Não repita apenas o nome. Por exemplo, descrever a opção `NLS` como "incluir suporte NLS" não ajuda o usuário, que já pode ver o nome da opção, mas pode não saber o que isso significa. Descrevendo-a como "Suporte a idiomas nativos por meio de utilitários gettext" é muito mais útil. ==== [IMPORTANT] ==== Os nomes das opções são sempre em letras maiúsculas. Não podem estar misturadas ou apenas em minúsculo. ==== `OPTIONS` podem ser agrupadas como opções radio, onde apenas uma escolha de cada grupo é permitida: [.programlisting] .... OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4 .... [WARNING] ==== _Deve_ estar sempre selecionada uma de cada `OPTIONS_SINGLE` para as opções serem válidas. Uma opção de cada grupo _deve_ ser adicionada a `OPTIONS_DEFAULT`. ==== `OPTIONS` podem ser agrupadas como opções radio, onde nenhuma ou apenas uma escolha de cada grupo é permitida: [.programlisting] .... OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8 .... `OPTIONS` também pode ser agrupadas como listas de "múltipla-escolha", onde _pelo menos uma_ opção deve estar habilitada: [.programlisting] .... OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6 .... `OPTIONS` também pode ser agrupadas como listas de "múltipla-escolha", onde nenhuma ou qualquer opção pode ser ativada: [.programlisting] .... OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10 .... `OPTIONS` são desativadas por padrão, a menos que estejam listadas em `OPTIONS_DEFAULT`: [.programlisting] .... OPTIONS_DEFAULT= OPT1 OPT3 OPT6 .... Definições de `OPTIONS` devem aparecer antes da inclusão de [.filename]#bsd.port.options.mk#. Valores de `PORT_OPTIONS` só podem ser testados após a inclusão de [.filename]#bsd.port.options.mk#. Inclusão de [.filename]#bsd.port.pre.mk# pode ser usado também, e ainda é amplamente usado em ports escritos antes da introdução de [.filename]#bsd.port.options.mk#. Mas esteja ciente de que algumas variáveis não funcionarão como esperado após a inclusão de [.filename]#bsd.port.pre.mk#, tipicamente algumas flags `USE_*`. [[ports-options-simple-use]] .Uso Simples de `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= FOO BAR OPTIONS_DEFAULT=FOO FOO_DESC= Option foo support BAR_DESC= Feature bar support # Will add --with-foo / --without-foo FOO_CONFIGURE_WITH= foo BAR_RUN_DEPENDS= bar:bar/bar .include .... ==== [[ports-options-check-unset]] .Verificar `OPTIONS` Desmacadas [example] ==== [.programlisting] .... .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif .... O formato acima não é recomendado. O método preferido é usar um configure knob para realmente ativar e desativar o recurso coincidindo com a opção: [.programlisting] .... # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples .... ==== [[ports-options-practical-use]] .Uso Prático de `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= EXAMPLES OPTIONS_DEFAULT= PGSQL LDAP SSL OPTIONS_SINGLE= BACKEND OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB OPTIONS_MULTI= AUTH OPTIONS_MULTI_AUTH= LDAP PAM SSL EXAMPLES_DESC= Install extra examples MYSQL_DESC= Use MySQL as backend PGSQL_DESC= Use PostgreSQL as backend BDB_DESC= Use Berkeley DB as backend LDAP_DESC= Build with LDAP authentication support PAM_DESC= Build with PAM support SSL_DESC= Build with OpenSSL support # Will add USE_PGSQL=yes PGSQL_USE= pgsql=yes # Will add --enable-postgres / --disable-postgres PGSQL_CONFIGURE_ENABLE= postgres ICU_LIB_DEPENDS= libicuuc.so:devel/icu # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples # Check other OPTIONS .include .... ==== [[makefile-options-default]] ==== Opções Padrão Essas opções estão sempre ativadas por padrão. * `DOCS` -- build and install documentation. * `NLS` -- Native Language Support. * `EXAMPLES` -- build and install examples. * `IPV6` -- IPv6 protocol support. [NOTE] ==== Não há necessidade de adicioná-las em `OPTIONS_DEFAULT`. Para ativá-las e mostra-las na caixa de diálogo de seleção de opções, elas devem ser adicionadas em `OPTIONS_DEFINE`. ==== [[makefile-options-auto-activation]] === Feature de Ativação Automática Ao usar um script configure GNU, fique de olho em quais recursos opcionais são ativados por detecção automática. Desative explicitamente os recursos opcionais que não são necessários, adicionando `--without-xxx` ou `--disable-xxx` em `CONFIGURE_ARGS`. [[makefile-options-auto-activation-bad]] .Manipulação Incorreta de uma Opção [example] ==== [.programlisting] .... .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:devel/foo CONFIGURE_ARGS+= --enable-foo .endif .... ==== No exemplo acima, imagine que uma biblioteca libfoo está instalada no sistema. O usuário não quer que este aplicativo use libfoo, então ele desabilitou a opção na caixa de diálogo do `make config`. Mas o script configure do aplicativo detecta a biblioteca presente no sistema e inclui seu suporte no executável resultante. Agora, quando o usuário decide remover libfoo do sistema, o sistema de ports não protesta (nenhuma dependência de libfoo foi registrada), e então o aplicativo quebra. [[makefile-options-auto-activation-good]] .Manuseio Correto de uma Opção [example] ==== [.programlisting] .... FOO_LIB_DEPENDS= libfoo.so:devel/foo # Will add --enable-foo / --disable-foo FOO_CONFIGURE_ENABLE= foo .... ==== [NOTE] ==== Sob algumas circunstâncias, a sintaxe condicional abreviada pode causar problemas com construções complexas. Os erros são geralmente `Malformed conditional`, e uma sintaxe alternativa pode ser usada. [.programlisting] .... .if !empty(VARIABLE:MVALUE) .... como uma alternativa para [.programlisting] .... .if ${VARIABLE:MVALUE} .... ==== [[options-helpers]] === Assistentes de Opções Existem algumas macros para ajudar a simplificar valores condicionais que diferem com base nas opções definidas. Para facilitar o acesso, é fornecida uma lista abrangente: `PLIST_SUB`, `SUB_LIST`:: Para geração automática de `%%_OPT_%%` e `%%NO_OPT%%`, veja <>. + Para uso mais complexo, veja <>. `CONFIGURE_ARGS`:: Para `--enable-_x_` e `--disable-_x_`, veja <>. + Para `--with-_x_` e `--without-_x_`, veja <>. + Para todos os outros casos, veja <>. `CMAKE_ARGS`:: Para argumentos que são booleanos (`on`, `off`, `true`, `false`, `0`, `1`) veja <>. + Para todos os outros casos, veja <>. `MESON_ARGS`:: Para argumentos que precisam de `true` ou `false`, veja <>. + Para argumentos que precisam de `yes` ou `no`, use <>. + Para argumentos que precisam de `true` ou `false`, veja <>. + Para todos os outros casos, use <>. `QMAKE_ARGS`:: Veja <>. `USE_*`:: Veja <>. `*_DEPENDS`:: Veja <>. _*_ (Qualquer variável):: As variáveis ​​mais usadas possuem assistentes diretos, veja <>. + Para qualquer variável sem um assistente específico, veja <>. Dependências de opções:: Quando uma opção precisa de outra opção para funcionar, veja <>. Conflitos de opções:: Quando uma opção não funciona se outra também estiver ativada, consulte <>. Targets para Build:: Quando uma opção precisa de algum processamento extra, veja <>. [[options_sub]] ==== `OPTIONS_SUB` Se `OPTIONS_SUB` está definido com `yes` então cada uma das opções adicionadas a `OPTIONS_DEFINE` será adicionada em `PLIST_SUB` e `SUB_LIST`, por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} PLIST_SUB+= OPT1="" NO_OPT1="@comment " SUB_LIST+= OPT1="" NO_OPT1="@comment " .else PLIST_SUB+= OPT1="@comment " NO_OPT1="" SUB_LIST+= OPT1="@comment " NO_OPT1="" .endif .... [NOTE] ==== O valor de `OPTIONS_SUB` é ignorado. Definindo-o com qualquer valor irá adicionar entradas `PLIST_SUB` e `SUB_LIST` para _todas_ as opções. ==== [[options-use]] ==== `OPT_USE` e `OPT_USE_OFF` Quando a opção _OPT_ é selecionada, para cada par `_key=value_` em `OPT_USE`, _value_ é anexado ao `USE_KEY` correspondente. E se _value_ tiver espaços, substitua-os por vírgulas e eles serão alterados de volta para espaços durante o processamento. `OPT_USE_OFF` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES= xorg OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr OPT1_USE_OFF= openssl=yes .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} USE_MYSQL= yes USES+= xorg USE_XORG= x11 xextproto xext xrandr .else USE_OPENSSL= yes .endif .... [[options-configure-helpers]] ==== Assistentes `CONFIGURE_ARGS` [[options-configure_enable]] ===== `OPT_CONFIGURE_ENABLE` Quando a opção _OPT_ é selecionada, para cada _valor_ em `OPT_CONFIGURE_ENABLE`, `--enable-_valor_` será anexado a `CONFIGURE_ARGS`. Quando a opção OPT _não for_ selecionada, `--disable-_valor_` será anexado a `CONFIGURE_ARGS`. Um argumento opcional pode ser especificado com um símbolo `=`. Este argumento é apenas anexado na entrada de opção do script configure `--enable-_valor_`. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_ENABLE= test1 test2 OPT2_CONFIGURE_ENABLE= test2=exhaustive .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-test1 --enable-test2 .else CONFIGURE_ARGS+= --disable-test1 --disable-test2 .endif .if ${PORT_OPTIONS:MOPT2} CONFIGURE_ARGS+= --enable-test2=exhaustive .else CONFIGURE_ARGS+= --disable-test2 .endif .... [[options-configure_with]] ===== `OPT_CONFIGURE_WITH` Quando a opção _OPT_ é selecionada, para cada _valor_ em `OPT_CONFIGURE_WITH`, `--with-_valor_` será anexado a `CONFIGURE_ARGS`. Quando a opção OPT_não for_ selecionada, `--without-_valor_` será anexado a `CONFIGURE_ARGS`. Um argumento opcional pode ser especificado com um símbolo `=`. Este argumento é apenas anexado na entrada de opção do script configure `--with-_valor_`. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_WITH= test1 OPT2_CONFIGURE_WITH= test2=exhaustive .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --with-test1 .else CONFIGURE_ARGS+= --without-test1 .endif .if ${PORT_OPTIONS:MOPT2} CONFIGURE_ARGS+= --with-test2=exhaustive .else CONFIGURE_ARGS+= --without-test2 .endif .... [[options-configure_on]] ===== `OPT_CONFIGURE_ON` e `OPT_CONFIGURE_OFF` Quando a opção _OPT_ é selecionada, o valor de `OPT_CONFIGURE_ON`, se definido, é anexado a `CONFIGURE_ARGS`. `OPT_CONFIGURE_OFF` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test OPT1_CONFIGURE_OFF= --no-test .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --add-test .else CONFIGURE_ARGS+= --no-test .endif .... [TIP] ==== Na maioria das vezes, os assistentes em <> e <> fornecem uma funcionalidade mais curta e abrangente. ==== [[options-cmake-helpers]] ==== Assistentes `CMAKE_ARGS` [[options-cmake_on]] ===== `OPT_CMAKE_ON` e `OPT_CMAKE_OFF` Quando a opção _OPT_ é selecionada, o valor de `OPT_CMAKE_ON`, se definido, é anexado a `CMAKE_ARGS`. `OPT_CMAKE_OFF` funciona da mesma maneira, mas quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true -DDEBUG:BOOL=true OPT1_CMAKE_OFF= -DOPTIMIZE:BOOL=true .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true .else CMAKE_ARGS+= -DOPTIMIZE:BOOL=true .endif .... [TIP] ==== Veja <> para um assistente mais curto quando o valor for booleano. ==== [[options-cmake_bool]] ===== `OPT_CMAKE_BOOL` e `OPT_CMAKE_BOOL_OFF` Quando a opção _OPT_ é selecionada, para cada _valor_ em `OPT_CMAKE_BOOL`, `-Dvalor:BOOL=true` será anexado a `CMAKE_ARGS`. Quando a opção OPT_não for_ selecionada, `-Dvalor:BOOL=false` será anexado a `CONFIGURE_ARGS`. O `OPT_CMAKE_BOOL_OFF` é o oposto, `-Dvalor:BOOL=false` será anexado a `CMAKE_ARGS` quando a opção é selecionada, e a entrada `-Dvalor:BOOL=true` quando a opção _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_BOOL= TEST DEBUG OPT1_CMAKE_BOOL_OFF= OPTIMIZE .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true \ -DOPTIMIZE:BOOL=false .else CMAKE_ARGS+= -DTEST:BOOL=false -DDEBUG:BOOL=false \ -DOPTIMIZE:BOOL=true .endif .... [[options-meson-helpers]] ==== Assistentes `MESON_ARGS` [[options-meson_on]] ===== `OPT_MESON_ON` e `OPT_MESON_OFF` Quando a opção _OPT_ é selecionada, o valor de `OPT_MESON_ON`, se definido, é anexado a `MESON_ARGS`. `OPT_MESON_OFF` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_ON= -Dopt=1 OPT1_MESON_OFF= -Dopt=2 .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dopt=1 .else MESON_ARGS+= -Dopt=2 .endif .... [[options-meson_true]] ===== `OPT_MESON_TRUE` e `OPT_MESON_FALSE` Quando a opção _OPT_ é selecionada, para cada _valor_ em `OPT_MESON_TRUE`, `-Dvalor=true` será anexado a `MESON_ARGS`. Quando a opção OPT_não for_ selecionada, `-Dvalor=false` será anexado a `MESON_ARGS`. O `OPT_MESON_FALSE` é o oposto, a entrada `-Dvalor=false` será anexado a `MESON_ARGS` quando a opção for selecionada e a entrada `-Dvalor=true` quando a opção _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_TRUE= test debug OPT1_MESON_FALSE= optimize .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=true -Ddebug=true \ -Doptimize=false .else MESON_ARGS+= -Dtest=false -Ddebug=false \ -Doptimize=true .endif .... [[options-meson_yes]] ===== `OPT_MESON_YES` e `OPT_MESON_NO` Quando a opção _OPT_ é selecionada, para cada _entrada_ dentro da variável `OPT_MESON_YES` a entrada `-D__=yes` é anexada a variável `MESON_ARGS`. Quando a opção OPT _não é_ selecionada, então a entrada `-D=no` é anexada a variável `MESON_ARGS`. O `OPT_MESON_NO` é o oposto, a entrada `-D=no` é anexada a variável `MESON_ARGS` quando a opção é selecionada e a entrada `-D=yes` quando a opção _não é_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_YES= test debug OPT1_MESON_NO= optimize .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=yes -Ddebug=yes \ -Doptimize=no .else MESON_ARGS+= -Dtest=no -Ddebug=no \ -Doptimize=yes .endif .... [[options-meson_enabled]] ===== `OPT_MESON_ENABLED` e `OPT_MESON_DISABLED` Quando a opção _OPT_ é selecionada, para cada _valor_ em `OPT_MESON_ENABLED`, `-Dvalor=enabled` será anexado a `MESON_ARGS`. Quando a opção OPT_não for_ selecionada, `-Dvalor=disabled` será anexado a `MESON_ARGS`. O `OPT_MESON_DISABLED` é o oposto, a entrada `-Dvalor=disabled` será anexado a `MESON_ARGS` quando a opção for selecionada e a entrada `-Dvalor=enabled` quando a opção _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_ENABLED= test OPT1_MESON_DISABLED= debug .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=enabled -Ddebug=disabled .else MESON_ARGS+= -Dtest=disabled -Ddebug=enabled .endif .... [[options-qmake_on]] ==== `OPT_QMAKE_ON` e `OPT_QMAKE_OFF` Quando a opção _OPT_ é selecionada, o valor de `OPT_QMAKE_ON`, se definido, é anexado a `QMAKE_ARGS`. `OPT_QMAKE_OFF` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_QMAKE_ON= -DTEST:BOOL=true OPT1_QMAKE_OFF= -DPRODUCTION:BOOL=true .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} QMAKE_ARGS+= -DTEST:BOOL=true .else QMAKE_ARGS+= -DPRODUCTION:BOOL=true .endif .... [[options-implies]] ==== `OPT_IMPLIES` Fornece uma maneira de adicionar dependências entre as opções. Quando _OPT_ for selecionada, todas as opções listadas nesta variável também serão selecionadas. Usando o <> descrito anteriormente para demonstrar: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_IMPLIES= OPT2 OPT1_CONFIGURE_ENABLE= opt1 OPT2_CONFIGURE_ENABLE= opt2 .... É equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-opt1 .else CONFIGURE_ARGS+= --disable-opt1 .endif .if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-opt2 .else CONFIGURE_ARGS+= --disable-opt2 .endif .... [[options-implies-ex1]] .Uso Simples de `OPT_IMPLIES` [example] ==== Este port tem uma opção `X11` e uma opção `GNOME` que precisa da opção `X11` selecionada para poder compilar. [.programlisting] .... OPTIONS_DEFINE= X11 GNOME OPTIONS_DEFAULT= X11 X11_USES= xorg X11_USE= xorg=xi,xextproto GNOME_USE= gnome=gtk30 GNOME_IMPLIES= X11 .... ==== [[options-prevents]] ==== `OPT_PREVENTS` e `OPT_PREVENTS_MSG` Fornece uma maneira de adicionar conflitos entre as opções. Quando _OPT_ for selecionada, todas as opções listadas em `OPT_PREVENTS` devem estar desmarcadas. Se `OPT_PREVENTS_MSG` estiver definido e um conflito for acionado, seu conteúdo será exibido explicando o por que do conflito. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_PREVENTS= OPT2 OPT1_PREVENTS_MSG= OPT1 and OPT2 enable conflicting options .... É aproximadamente equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT2} && ${PORT_OPTIONS:MOPT1} BROKEN= Option OPT1 conflicts with OPT2 (select only one) .endif .... A única diferença é que o primeiro irá apresentar um erro depois de executar `make config`, sugerindo alterar as opções selecionadas. [[options-prevents-ex1]] .Uso Simples de `OPT_PREVENTS` [example] ==== Este port tem as opções `X509` e `SCTP`. Ambas as opções adicionam patches, mas os patches entram em conflito uns com os outros, então eles não podem ser selecionados ao mesmo tempo. [.programlisting] .... OPTIONS_DEFINE= X509 SCTP SCTP_PATCHFILES= ${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1 SCTP_CONFIGURE_WITH= sctp X509_PATCH_SITES= http://www.roumenpetrov.info/openssh/x509/:x509 X509_PATCHFILES= ${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509 X509_PREVENTS= SCTP X509_PREVENTS_MSG= X509 and SCTP patches conflict .... ==== [[options-vars]] ==== `OPT_VARS` e `OPT_VARS_OFF` Fornece uma maneira genérica de definir e acrescentar valores em variáveis. [WARNING] ==== Antes de usar `OPT_VARS` e `OPT_VARS_OFF`, veja se já não existe um assistente mais específico disponível em <>. ==== Quando a opção _OPT_ está selecionada e `OPT_VARS` definido, os pares `_chave_=_valor_` e `_chave_+=_valor_` são avaliados a partir da variável `OPT_VARS`. Um `=` sobrescreve o valor existente da `CHAVE`, um `+=` acrescenta o valor a chave. `OPT_VARS_OFF` funciona da mesma maneira, quando a opção `OPT` _não for_ selecionada. [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT3 OPT1_VARS= also_build+=bin1 OPT2_VARS= also_build+=bin2 OPT3_VARS= bin3_build=yes OPT3_VARS_OFF= bin3_build=no MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}" .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}" .include .if ${PORT_OPTIONS:MOPT1} ALSO_BUILD+= bin1 .endif .if ${PORT_OPTIONS:MOPT2} ALSO_BUILD+= bin2 .endif .if ${PORT_OPTIONS:MOPT2} BIN3_BUILD= yes .else BIN3_BUILD= no .endif .... [IMPORTANT] ==== Valores contendo espaços em branco devem ser colocados entre aspas: [.programlisting] .... OPT_VARS= foo="bar baz" .... Isso se deve ao jeito que a variável de expansão man:make[1] lida com espaço em branco. Quando a opção `OPT_VARS=foo=bar baz` é expandida, a variável acaba contendo duas strings, `foo=bar` e `baz`. Mas quem está submetendo o código provavelmente pretendia que houvesse apenas uma string, `foo=bar baz`. Inserir o valor entre aspas impede que o espaço em branco seja usado como um delimitador. Além disso, _não_ adicione espaços extras após o símbolo `_var_=` e antes do valor, pois assim também seria dividido o valor em duas strings. _Isso não irá funcionar_: [.programlisting] .... OPT_VARS= foo= bar .... ==== [[options-dependencies]] ==== Dependências, `OPT_DEPTYPE_` e `OPT_DEPTYPE_OFF` Para qualquer um desses tipos de dependência: * `PKG_DEPENDS` * `EXTRACT_DEPENDS` * `PATCH_DEPENDS` * `FETCH_DEPENDS` * `BUILD_DEPENDS` * `LIB_DEPENDS` * `RUN_DEPENDS` Quando opção _OPT_ é selecionada, o valor de `OPT_DEPTYPE`, se definido, é anexado a `_DEPTYPE_`. `OPT_DEPTYPE_OFF` funciona da mesma forma, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:devel/a OPT1_LIB_DEPENDS_OFF= libb.so:devel/b .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:devel/a .else LIB_DEPENDS+= libb.so:devel/b .endif .... [[options-variables]] ==== Substituição de Variáveis ​​Genéricas, `OPT_VARIABLE_` e `OPT_VARIABLE_OFF` Para qualquer uma destas variáveis: * `ALL_TARGET` * `BINARY_ALIAS` * `BROKEN` * `CATEGORIES` * `CFLAGS` * `CONFIGURE_ENV` * `CONFLICTS` * `CONFLICTS_BUILD` * `CONFLICTS_INSTALL` * `CPPFLAGS` * `CXXFLAGS` * `DESKTOP_ENTRIES` * `DISTFILES` * `EXTRACT_ONLY` * `EXTRA_PATCHES` * `GH_ACCOUNT` * `GH_PROJECT` * `GH_SUBDIR` * `GH_TAGNAME` * `GH_TUPLE` * `GL_ACCOUNT` * `GL_COMMIT` * `GL_PROJECT` * `GL_SITE` * `GL_SUBDIR` * `GL_TUPLE` * `IGNORE` * `INFO` * `INSTALL_TARGET` * `LDFLAGS` * `LIBS` * `MAKE_ARGS` * `MAKE_ENV` * `MASTER_SITES` * `PATCHFILES` * `PATCH_SITES` * `PLIST_DIRS` * `PLIST_FILES` * `PLIST_SUB` * `PORTDOCS` * `PORTEXAMPLES` * `SUB_FILES` * `SUB_LIST` * `TEST_TARGET` * `USES` Quando a opção _OPT_ é selecionada, o valor da variável `OPT_ABOVEVARIABLE`, se definido, é anexado a `_ABOVEVARIABLE_`. `OPT_ABOVEVARIABLE_OFF` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS_OFF= -DTEST .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} USES+= gmake .else CFLAGS+= -DTEST .endif .... [NOTE] ==== Algumas variáveis ​​não estão nesta lista, em particular `PKGNAMEPREFIX` e `PKGNAMESUFFIX`. Isso é intencional. Um port _não deve_ mudar seu nome quando alguma de suas opções forem alteradas. ==== [WARNING] ==== Algumas dessas variáveis, pelo menos `ALL_TARGET`, `DISTFILES` e `INSTALL_TARGET`, tem seus valores padrão definidos _depois_ das opções serem processadas. Com estas linhas no [.filename]#Makefile#: [.programlisting] .... ALL_TARGET= all DOCS_ALL_TARGET= doc .... Se a opção `DOCS` estiver ativada, `ALL_TARGET` terá o valor `all doc`; se a opção estiver desativada, ela terá o valor `all`. Com apenas a linha do assistente de opções no [.filename]#Makefile#: [.programlisting] .... DOCS_ALL_TARGET= doc .... Se a opção `DOCS` estiver ativada, `ALL_TARGET` terá o valor `doc`; se a opção estiver desativada, ela terá o valor `all`. ==== [[options-targets]] ==== Targets Adicionais de Compilação, `_target_-_OPT_-on` e `_target_-_OPT_-off` Estes targets de [.filename]#Makefile# podem aceitar targets extras de compilação: * `pre-fetch` * `do-fetch` * `post-fetch` * `pre-extract` * `do-extract` * `post-extract` * `pre-patch` * `do-patch` * `post-patch` * `pre-configure` * `do-configure` * `post-configure` * `pre-build` * `do-build` * `post-build` * `pre-install` * `do-install` * `post-install` * `post-stage` * `pre-package` * `do-package` * `post-package` Quando a opção _OPT_ é selecionada, o target `_TARGET_-_OPT_-on`, se definido, é executado após `_TARGET_`. `_TARGET_-_OPT_-off` funciona da mesma maneira, quando `OPT` _não for_ selecionada. Por exemplo: [.programlisting] .... OPTIONS_DEFINE= OPT1 post-patch-OPT1-on: @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${EXAMPLESDIR}/|' ${WRKSRC}/Makefile post-patch-OPT1-off: @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${PREFIX}/bin/|' ${WRKSRC}/Makefile .... é equivalente a: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include post-patch: .if ${PORT_OPTIONS:MOPT1} @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${EXAMPLESDIR}/|' ${WRKSRC}/Makefile .else @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${PREFIX}/bin/|' ${WRKSRC}/Makefile .endif .... [[makefile-wrkdir]] == Especificando o Diretório de Trabalho Cada port é extraído em um diretório de trabalho, que deve ter permissão de escrita. O sistema de ports tem por padrão os `DISTFILES` descompactado em um diretório chamado `${DISTNAME}`. Em outras palavras, se o [.filename]#Makefile# tem: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0 .... então os arquivos de distribuição do port contêm um diretório de nível superior, [.filename]#foo-1.0#, e o resto dos arquivos estão localizados nesse diretório. Diversas variáveis ​​podem ser substituídas se não for esse o caso. [[makefile-wrksrc]] === `WRKSRC` A variável lista o nome do diretório que é criado quando os distfiles do aplicativo são extraídos. Se o exemplo anterior for extraído em um diretório chamado [.filename]#foo# (e não [.filename]#foo-1.0#) escreva: [.programlisting] .... WRKSRC= ${WRKDIR}/foo .... ou possivelmente [.programlisting] .... WRKSRC= ${WRKDIR}/${PORTNAME} .... [[makefile-wrksrc_subdir]] === `WRKSRC_SUBDIR` Se o código fonte necessário para o port estiver em um subdiretório do arquivo de distribuição extraído, defina `WRKSRC_SUBDIR` para esse diretório. [.programlisting] .... WRKSRC_SUBDIR= src .... [[makefile-no_wrksubdir]] === `NO_WRKSUBDIR` Se o port não extrair para nenhum subdiretório, então configure `NO_WRKSUBDIR` para indicar isso. [.programlisting] .... NO_WRKSUBDIR= yes .... [NOTE] ==== Porque `WRKDIR` é o único diretório que deve ter permissão de escrita durante a compilação e é usado para armazenar muitos arquivos que registram o status da compilação, a extração do port será forçada para um subdiretório. ==== [[conflicts]] == Manipulando Conflitos Existem três variáveis ​​diferentes para registrar um conflito entre pacotes e ports: `CONFLICTS`, `CONFLICTS_INSTALL` e `CONFLICTS_BUILD`. [NOTE] ==== -As variáveis ​​de conflito definem automaticamente a variável `IGNORE`, que é mais amplamente documentada em <>. +As variáveis ​​de conflito definem automaticamente a variável `IGNORE`, que é mais amplamente documentada em crossref:porting-dads[dads-noinstall,Marcando um Port não Instalável com a variável `BROKEN` `FORBIDDEN` ou `IGNORE`]. ==== Ao remover um dos vários ports conflitados, é aconselhável reter `CONFLICTS` nos outros ports por alguns meses para atender usuários que apenas fazem atualizações de vez em quando. [[conclicts-conflicts_install]] `CONFLICTS_INSTALL`:: Se o pacote não puder coexistir com outros pacotes (devido a conflitos de arquivos, incompatibilidades de tempo de execução, etc.). A checagem `CONFLICTS_INSTALL` é feita após o estágio de compilação e antes do estágio de instalação. [[conclicts-conflicts_build]] `CONFLICTS_BUILD`:: Se o port não puder ser compilado quando outros ports específicos já estiverem instalados. Conflitos de compilação não serão registrados no pacote final. [[conclicts-conflicts]] `CONFLICTS`:: Se o port não puder ser compilado quando um certo port estiver instalado e o pacote final não puder coexistir com o outro pacote. A checagem `CONFLICTS` é feita antes do estágio de compilação e antes do estágio de instalação. O conteúdo mais comum de uma dessas variáveis ​​é o pacote base de outro port. O pacote base é o nome do pacote sem a versão, ele pode ser obtido executando `make -V PKGBASE`. [[conflicts-ex1]] .Uso básico de `CONFLICTS_*` [example] ==== package:dns/bind99[] não pode ser instalado se package:dns/bind910[] está presente porque eles instalam os mesmos arquivos. Primeiro, reúna o pacote base para usar: [source,shell] .... % make -C dns/bind99 -V PKGBASE bind99 % make -C dns/bind910 -V PKGBASE bind910 .... Então adicione ao [.filename]#Makefile# do package:dns/bind99[]: [.programlisting] .... CONFLICTS_INSTALL= bind910 .... E adicione ao [.filename]#Makefile# do package:dns/bind910[]: [.programlisting] .... CONFLICTS_INSTALL= bind99 .... ==== Às vezes, apenas uma versão de outro port é incompatível, neste caso, use o nome completo do pacote, com a versão, e use shell globs, como `*` e `?` para garantir que todas as versões possíveis sejam correspondidas. [[conflicts-ex2]] .Usando `CONFLICTS_*` Com Globs. [example] ==== Nas versões 2.0 até 2.4.1_2, package:deskutils/gnotime[] instalava uma versão integrada de package:databases/qof[]. Para refletir este passado, o [.filename]#Makefile# do package:database/qof[] contém: [.programlisting] .... CONFLICTS_INSTALL= gnotime-2.[0-3]* \ gnotime-2.4.0* gnotime-2.4.1 \ gnotime-2.4.1_[12] .... As primeira entrada corresponde as versões `2.0` até `2.3`, a segunda corresponde todas as revisões de `2.4.0`, a terceira corresponde a versão exata `2.4.1`, e a última corresponde a primeira e segunda revisão da versão `2.4.1`. package:deskutils/gnotime[] não possui nenhuma linha de conflitos porque sua versão atual não conflita com mais nada. ==== [[install]] == Instalando Arquivos [IMPORTANT] ==== O estágio `install` é muito importante para o usuário final porque ele adiciona arquivos ao sistema. Todos os comandos adicionais de estágios `*-install` dos [.filename]#Makefile#'s de port devem ser mostrados na tela. _Não_ silencie esses comandos com `@` ou `.SILENT`. ==== [[install-macros]] === Macros `INSTALL_*` -Use as macros fornecidas em [.filename]#bsd.port.mk# para garantir a propriedade correta dos arquivos nos targets `*-install` do port. Defina a propriedade diretamente em [.filename]#pkg-plist# com as entradas correspondentes, como `@(_owner_,_group_,)`, `@owner _owner_`, e `@group _group_`. Esses operadores funcionam até serem substituídos, ou até o final do [.filename]#pkg-plist#, lembre-se de redefini-los depois que eles não forem mais necessários. O valor de propriedade padrão é `root:wheel`. Veja <> para maiores informações. +Use as macros fornecidas em [.filename]#bsd.port.mk# para garantir a propriedade correta dos arquivos nos targets `*-install` do port. Defina a propriedade diretamente em [.filename]#pkg-plist# com as entradas correspondentes, como `@(_owner_,_group_,)`, `@owner _owner_`, e `@group _group_`. Esses operadores funcionam até serem substituídos, ou até o final do [.filename]#pkg-plist#, lembre-se de redefini-los depois que eles não forem mais necessários. O valor de propriedade padrão é `root:wheel`. Veja crossref:plist[plist-keywords-base,Keywords Básicas] para maiores informações. * `INSTALL_PROGRAM` é um comando para instalar executáveis ​​binários. * `INSTALL_SCRIPT` é um comando para instalar scripts executáveis. * `INSTALL_LIB` é um comando para instalar bibliotecas compartilhadas (mas não bibliotecas estáticas). * `INSTALL_KLD` é um comando para instalar módulos carregáveis ​​do kernel. Algumas arquiteturas não gostam de ter os módulos otimizados (stripped), então use este comando em vez de `INSTALL_PROGRAM`. * `INSTALL_DATA` é um comando para instalar dados compartilháveis, incluindo bibliotecas estáticas. * `INSTALL_MAN` é um comando para instalar manpages e outras documentações (ele não realiza nenhuma compactação). Estas variáveis ​​parametrizam o comando man:install[1] com as flags apropriadas para cada situação. [IMPORTANT] ==== Não use `INSTALL_LIB` para instalar bibliotecas estáticas, porque otimiza-las (strip) torna-as sem utilidade. Use `INSTALL_DATA` neste caso. ==== [[install-strip]] === Otimizando (Stripping) Binários e Bibliotecas Compartilhadas Os binários instalados devem ser otimizados (stripped). Não otimize (strip) os binários manualmente, a menos que seja absolutamente necessário. A macro `INSTALL_PROGRAM` instala e otimiza (strip) o binário ao mesmo tempo. A macro `INSTALL_LIB` faz o mesmo com as bibliotecas compartilhadas. Quando um arquivo deve ser otimizado (stripped), mas as macros `INSTALL_PROGRAM` e `INSTALL_LIB` não são desejadas, `${STRIP_CMD}` otimiza (strips) o programa ou a biblioteca compartilhada. Isso geralmente é feito no target `post-install`. Por exemplo: [.programlisting] .... post-install: ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl .... Quando vários arquivos precisam ser otimizados (stripped): [.programlisting] .... post-install: .for l in geometry media body track world ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 .endfor .... Use man:file[1] em um arquivo para determinar se ele foi otimizado (stripped). Binários são relatados por man:file[1] como `stripped` ou `not stripped`. Além disso,man:strip[1] irá detectar programas que já foram otimizados (stripped) e retornar o comando sem erros. [IMPORTANT] ==== Quando `WITH_DEBUG` estiver definido, os arquivos elf _não devem_ ser otimizados (stripped). -As variáveis ​​(`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) e <> fornecidas pelo framework lidam com isso automaticamente. +As variáveis ​​(`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) e crossref:uses[uses,`USES`] fornecidas pelo framework lidam com isso automaticamente. Alguns softwares, adicionam `-s` em seus `LDFLAGS`, neste caso, ou remova o `-s` se `WITH_DEBUG` estiver definido, ou remova o incondicionalmente e use `STRIP_CMD` em `post-install`. ==== [[install-copytree]] === Instalando uma Árvore Inteira de Arquivos -Às vezes, um grande número de arquivos devem ser instalados preservando sua organização hierárquica. Por exemplo, copiando de uma árvore de diretórios inteira do `WRKSRC` para um diretório de destino sob `PREFIX`. Observe que `PREFIX`, `EXEMPLESDIR`, `DATADIR` e outras variáveis ​​de caminho sempre devem ser precedidas por `STAGEDIR` para respeitar o staging (ver <>). +Às vezes, um grande número de arquivos devem ser instalados preservando sua organização hierárquica. Por exemplo, copiando de uma árvore de diretórios inteira do `WRKSRC` para um diretório de destino sob `PREFIX`. Observe que `PREFIX`, `EXEMPLESDIR`, `DATADIR` e outras variáveis ​​de caminho sempre devem ser precedidas por `STAGEDIR` para respeitar o staging (ver crossref:special[staging,Staging]). Existem duas macros para essa situação. A vantagem de usar essas macros em vez de `cp` é que elas garantem a propriedade e permissão adequada dos arquivos nos arquivos de destino. A primeira macro, `COPYTREE_BIN`, irá definir todos os arquivos instalados como sendo executáveis, sendo assim, adequado para instalações em [.filename]#PREFIX/bin#. A segunda macro,`COPYTREE_SHARE`, não define permissões de execução nos arquivos e, portanto, é adequado para instalar arquivos sob o destino [.filename]#PREFIX/share#. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR}) .... Este exemplo irá instalar o conteúdo do diretório [.filename]#exemples# do distfile do fornecedor para o local de exemplos apropriado do port. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DATADIR}/summer (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer) .... E este exemplo irá instalar os dados dos meses de verão no subdiretório [.filename]#summer# de um [.filename]#DATADIR#. Argumentos `find` adicionais podem ser passados através do terceiro argumento para `COPYTREE_*`. Por exemplo, para instalar todos os arquivos do primeiro exemplo, exceto Makefiles, é possível usar esses comandos. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && \ ${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR} "! -name Makefile") .... Essas macros não adicionam os arquivos instalados em [.filename]#pkg-plist#. Eles devem ser adicionados manualmente. Para documentação opcional (`PORTDOCS`, veja <>) e exemplos (`PORTEXAMPLES`), os prefixos `%%PORTDOCS%%` ou `%%PORTEXAMPLES%%` devem ser prefixados no [.filename]#pkg-plist#. [[install-documentation]] === Instalar Documentação Adicional Se o software tiver alguma documentação diferente do manual padrão e páginas de informações úteis para o usuário, instale-os em `DOCSDIR`. Isso pode ser feito como no item anterior, no target `post-install`. Crie um novo diretório para o port. O nome do diretório é `DOCSDIR`. Isso geralmente é igual a `PORTNAME`. No entanto, se o usuário desejar que versões diferentes do port sejam instaladas ao mesmo tempo, `PKGNAME` pode ser usado. -Já que apenas os arquivos listados no [.filename]#pkg-plist# são instalados, é seguro sempre instalar documentações no `STAGEDIR` (veja <>). Por isso, blocos `.if` são necessários apenas quando os arquivos forem grandes o suficiente para causarem sobrecarga significativa de I/O. +Já que apenas os arquivos listados no [.filename]#pkg-plist# são instalados, é seguro sempre instalar documentações no `STAGEDIR` (veja crossref:special[staging,Staging]). Por isso, blocos `.if` são necessários apenas quando os arquivos forem grandes o suficiente para causarem sobrecarga significativa de I/O. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR} .... Por outro lado, se houver uma opção DOCS no port, instale a documentação em um taget `post-install-DOCS-on`. Esses targets são descritos em <>. Aqui estão algumas variáveis úteis e como elas são expandidas por padrão quando usadas no [.filename]#Makefile#: * `DATADIR` é expandido para [.filename]#PREFIX/shared/PORTNAME#. * `DATADIR_REL` é expandido para [.filename]#share/PORTNAME#. * `DOCSDIR` é expandido para [.filename]#PREFIX/shared/doc/PORTNAME#. * `DOCSDIR_REL` é expandido para [.filename]#share/doc/PORTNAME#. * `EXEMPLESDIR` é expandido para [.filename]#PREFIX/shared/examples/PORTNAME#. * `EXAMPLESDIR_REL` é expandido para [.filename]#share/examples/PORTNAME#. [NOTE] ==== A opção `DOCS` controla apenas a documentação adicional instalada em `DOCSDIR`. Não se aplica a páginas de manual e páginas de informações padrão. Arquivos instalados em `EXEMPLESDIR` são controlados pela opção `EXEMPLES`. ==== Essas variáveis são exportadas para `PLIST_SUB`. Quando possível, seus valores aparecerão como nomes de caminho relativos ao [.filename]#PREFIX#. Isso é, por padrão [.filename]#share/doc/PORTNAME# será substituído por `%%DOCSDIR%%` na lista de empacotamento e assim por diante. (Saiba mais sobre substituições [.filename]#pkg-plist#<>.) Todos os arquivos e diretórios de documentação instalados condicionalmente são incluídos no [.filename]#pkg-plist# com o prefixo `%%PORTDOCS%%`, por exemplo: [.programlisting] .... %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT .... Como uma alternativa para listar os arquivos de documentação em [.filename]#pkg-plist#, um port pode definir a variável `PORTDOCS` com uma lista de nomes de arquivo e padrões shell glob para adicionar à lista de empacotamento final. Os nomes serão relativos a `DOCSDIR`. Portanto, um port que utiliza `PORTDOCS` e usa um local não padrão para sua documentação, deve definir `DOCSDIR` adequadamente. Se um diretório estiver listado em `PORTDOCS` ou ser correspondido por um padrão glob dessa variável, toda a sub árvore de arquivos e diretórios contidos serão registrados na lista final de empacotamento. Se a opção `DOCS` estiver desmarcada, os arquivos e diretórios listados em `PORTDOCS` não serão instalados ou adicionados à lista de empacotamento do port. A instalação da documentação em `PORTDOCS` como mostrado acima fica a cargo do port. Um exemplo típico de utilização `PORTDOCS`: [.programlisting] .... PORTDOCS= README.* ChangeLog docs/* .... [NOTE] ==== O equivalente de `PORTDOCS` para arquivos instalados em `DATADIR` e `EXEMPLESDIR` são `PORTDATA` e `PORTEXAMPLES`, respectivamente. O conteúdo de [.filename]#pkg-message# é exibido na instalação. Veja <> para mais detalhes. [.filename]#pkg-message# não precisa ser adicionado ao [.filename]#pkg-plist#. ==== [[install-subdirs]] === Subdiretórios Sob `PREFIX` Tente deixar o port colocar os arquivos nos subdiretórios corretos de `PREFIX`. Alguns ports juntam tudo e colocam os arquivos em um subdiretório com o nome do port, o que é incorreto. Além disso, muitos ports colocam todos arquivos, exceto binários, arquivos header e páginas de manual, em um subdiretório de [.filename]#lib#, o que não funciona bem com o paradigma BSD. Muitos dos arquivos devem ser movidos para um desses diretórios: [.filename]#etc#(setup/arquivos de configuração), [.filename]#libexec# (executáveis ​​iniciados internamente), [.filename]#sbin# (executáveis ​​para super-usuários/gerentes), [.filename]#info# (documentação para o navegador de informações) ou [.filename]#share# (arquivos independentes de arquitetura). Veja man:hier[7] para detalhes; as regras que regem [.filename]#/usr# praticamente se aplicam a [.filename]#/usr/local# também. A exceção são os ports que lidam com "notícias" USENET. Eles podem usar [.filename]#PREFIX/news# como um destino para seus arquivos. [[binary-alias]] == Use `BINARY_ALIAS` para Renomear Comandos Em Vez de Aplicar Patch na Compilação Quando `BINARY_ALIAS` é definido, ele criará links simbólicos dos comandos fornecidos, em um diretório que será prefixado para o `PATH`. Use-o para substituir comandos codificados na fase de compilação sem ter aplicar nenhum patch nos arquivos de compilação. [[binary-alias-ex1]] .Usando `BINARY_ALIAS` para Deixar `gsed` Disponível como `sed` [example] ==== Alguns ports esperam que o `sed` se comporte como o GNU sed e utilizam recursos que o man:sed[1] não possui. GNU sed está disponível em package:textproc/gsed[] no FreeBSD. Use `BINARY_ALIAS` para substituir `sed` com `gsed` durante a compilação: [.programlisting] .... BUILD_DEPENDS= gsed:textproc/gsed ... BINARY_ALIAS= sed=gsed .... ==== [[binary-alias-ex2]] .Usando `BINARY_ALIAS` Para Fornecer Aliases para Comandos `python3` Codificado [example] ==== Um port que possui uma referência codificada para `python3` em seus scripts de compilação precisará ter ele disponível no `PATH` em tempo de compilação. Use `BINARY_ALIAS` para criar um alias que aponte para o binário certo do Python 3: [.programlisting] .... USES= python:3.4+,build ... BINARY_ALIAS= python3=${PYTHON_CMD} .... -Veja <> para mais informações sobre `USES=python`. +Veja crossref:special[using-python,Usando Python] para mais informações sobre `USES=python`. ==== [NOTE] ==== Aliases binários são criados após as dependências fornecidas via `BUILD_DEPENDS` e `LIB_DEPENDS` serem processadas e antes do target `configure`. Isso leva a várias limitações. Por exemplo, os programas instalados via `TEST_DEPENDS` não podem ser usados para criar um alias binário, pois as dependências de teste especificadas desta forma são processadas após a criação dos aliases binários. ==== diff --git a/documentation/content/pt-br/books/porters-handbook/new-port/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/new-port/_index.adoc similarity index 96% rename from documentation/content/pt-br/books/porters-handbook/new-port/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/new-port/_index.adoc index eeb1c1c212..15bf8ef6dd 100644 --- a/documentation/content/pt-br/books/porters-handbook/new-port/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/new-port/_index.adoc @@ -1,56 +1,56 @@ --- title: Capítulo 2. Criando um Novo Port prev: books/porters-handbook/porting-why next: books/porters-handbook/quick-porting --- [[own-port]] = Criando um Novo Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 2 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Interessado em fazer um novo port ou atualizar os ports existentes? Ótimo! -O que segue são algumas instruções para criar um novo port para o FreeBSD. Para atualizar um port existente, leia este documento e depois leia o <>. +O que segue são algumas instruções para criar um novo port para o FreeBSD. Para atualizar um port existente, leia este documento e depois leia o crossref:upgrading[port-upgrading, Atualizando um Port]. Quando este documento não for suficientemente detalhado, consulte [.filename]#/usr/ports/Mk/bsd.port.mk#, que é incluído por todos os [.filename]##Makefile##s dos ports. Mesmo aqueles que não estão hackeando os [.filename]##Makefile##s diariamente podem ganhar muito conhecimento com isso. Além disso, perguntas específicas podem ser enviadas à http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[ Lista de discussão do ports do FreeBSD]. [NOTE] ==== Apenas uma fração das variáveis ​​(`_VAR_`) que podem ser sobrepostas são mencionados neste documento. A maioria (se não todas) estão documentadas no início do [.filename]#/usr/ports/Mk/bsd.port.mk#; as outras provavelmente deveriam estar também. Observe que esse arquivo usa uma configuração de tabulação não padrão: O Emacs e o Vim irão reconhecer a configuração ao carregar o arquivo. Ambos man:vi[1] e man:ex[1] podem ser configurados para usar o valor correto digitando `:set tabstop=4` uma vez que o arquivo foi carregado. ==== Procurando algo fácil para começar? Dê uma olhada na https://wiki.freebsd.org/WantedPorts[lista de ports desejados] e veja se você pode trabalhar em um (ou mais de um). diff --git a/documentation/content/pt-br/books/porters-handbook/order/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/order/_index.adoc similarity index 63% rename from documentation/content/pt-br/books/porters-handbook/order/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/order/_index.adoc index 78da146b3f..a75eb42b8d 100644 --- a/documentation/content/pt-br/books/porters-handbook/order/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/order/_index.adoc @@ -1,265 +1,265 @@ --- title: Chapter 15. Ordem das Variáveis ​​nos Makefiles de Port prev: books/porters-handbook/porting-samplem next: books/porters-handbook/keeping-up --- [[porting-order]] = Ordem das Variáveis ​​nos Makefiles de Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] As primeiras seções do [.filename]#Makefile# devem sempre vir na mesma ordem. Este padrão faz com que todos possam ler facilmente qualquer port sem ter que procurar variáveis em uma ordem aleatória. A primeira linha de um [.filename]#Makefile# é sempre um comentário contendo o ID de controle de versão do Subversion, seguido por uma linha vazia. Em novos ports, parece assim: [.programlisting] .... # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ .... Nos ports existentes, o Subversion expandiu essa entrada ficando assim: [.programlisting] .... # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ .... [NOTE] ==== As seções e variáveis descritas aqui são obrigatórias em um port comum. Em um port slave, muitas seções e variáveis podem ser ignoradas. ==== [IMPORTANT] ==== Cada bloco seguinte deve ser separado do bloco anterior por uma única linha em branco. Nos blocos a seguir, apenas defina as variáveis ​​que são requeridas pelo port. Defina essas variáveis ​​na ordem em que são mostradas aqui. ==== [[porting-order-portname]] == Bloco `PORTNAME` Este bloco é o mais importante. Ele define o nome do port, a versão, o local do arquivo de distribuição e a categoria. As variáveis ​​devem estar nesta ordem: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> (descontinuado) -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* crossref:makefiles[makefile-portname,`PORTNAME`] +* crossref:makefiles[makefile-versions,`PORTVERSION`][<>] +* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`] +* crossref:makefiles[makefile-versions,`DISTVERSION`][<>] +* crossref:makefiles[makefile-versions,`DISTVERSIONSUFFIX`] +* crossref:makefiles[makefile-portrevision,`PORTREVISION`] +* crossref:makefiles[makefile-portepoch,`PORTEPOCH`] +* crossref:makefiles[makefile-categories,`CATEGORIES`] +* crossref:makefiles[makefile-master_sites,`MASTER_SITES`] +* crossref:makefiles[makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`] (descontinuado) +* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`] +* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`] +* crossref:makefiles[makefile-distname,`DISTNAME`] +* crossref:makefiles[makefile-extract_sufx,`EXTRACT_SUFX`] +* crossref:makefiles[makefile-distfiles-definition,`DISTFILES`] +* crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`] +* crossref:makefiles[makefile-extract_only,`EXTRACT_ONLY`] [[porting-order-patch]] == Bloco `PATCHFILES` Este bloco é opcional. As variáveis ​​são: -* <> -* <> -* <> +* crossref:makefiles[porting-patchfiles,`PATCH_SITES`] +* crossref:makefiles[porting-patchfiles,`PATCHFILES`] +* crossref:makefiles[porting-patchfiles,`PATCH_DIST_STRIP`] [[porting-order-maintainer]] == Bloco `MAINTAINER` Este bloco é obrigatório. As variáveis ​​são: -* <> -* <> +* crossref:makefiles[makefile-maintainer,`MAINTAINER`] +* crossref:makefiles[makefile-comment,`COMMENT`] [[porting-order-license]] == Bloco `LICENSE` Este bloco é opcional, embora seja altamente recomendado. As variáveis ​​são: -* <> -* <> -* <> ou `LICENSE_GROUPS_NOME` -* <> ou `LICENSE_NAME_NOME` -* <> ou `LICENSE_TEXT_NOME` -* <> ou `LICENSE_FILE_NOME` -* <> ou `LICENSE_PERMS_NOME` -* <> ou `LICENSE_DISTFILES_NOME` +* crossref:makefiles[licenses-license,`LICENSE`] +* crossref:makefiles[licenses-license_comb,`LICENSE_COMB`] +* crossref:makefiles[licenses-license_groups,`LICENSE_GROUPS`] ou `LICENSE_GROUPS_NAME` +* crossref:makefiles[licenses-license_name,`LICENSE_NAME`] ou `LICENSE_NAME_NAME` +* crossref:makefiles[licenses-license_text,`LICENSE_TEXT`] ou `LICENSE_TEXT_NAME` +* crossref:makefiles[licenses-license_file,`LICENSE_FILE`] ou `LICENSE_FILE_NAME` +* crossref:makefiles[licenses-license_perms,`LICENSE_PERMS`] ou `LICENSE_PERMS_NAME_` +* crossref:makefiles[licenses-license_distfiles,`LICENSE_DISTFILES`] ou `LICENSE_DISTFILES_NAME` Se houver várias licenças, ordene as variáveis LICENSE_VAR_NOME pelo nome de licença. [[porting-order-broken]] == Mensagens Genéricas `BROKEN`/`IGNORE`/`DEPRECATED` Este bloco é opcional. As variáveis ​​são: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* crossref:porting-dads[dads-deprecated,`DEPRECATED`] +* crossref:porting-dads[dads-deprecated,`EXPIRATION_DATE`] +* crossref:porting-dads[dads-noinstall,`FORBIDDEN`] +* crossref:porting-dads[dads-noinstall,`BROKEN`] +* crossref:porting-dads[dads-noinstall,`BROKEN_*`] +* crossref:porting-dads[dads-noinstall,`IGNORE`] +* crossref:porting-dads[dads-noinstall,`IGNORE_*`] +* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS`] +* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS_REASON*`] +* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS`] +* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS_REASON*`] [NOTE] ==== -`BROKEN_*` e `IGNORE_*` podem ser qualquer variável genérica, por exemplo, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. Com exceção das variáveis ​​que dependem de uma variável <>, coloque essas em <>. Por exemplo, `IGNORE_WITH_PHP` só funciona se <> estiver definido e a variável `BROKEN_SSL` somente se <> estiver definido. +`BROKEN_*` e `IGNORE_*` podem ser qualquer variável genérica, por exemplo, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. Com exceção das variáveis ​​que dependem de uma variável crossref:uses[uses,`USES`], coloque essas em <>. Por exemplo, `IGNORE_WITH_PHP` só funciona se crossref:uses[xuses-php,`php`] estiver definido e a variável `BROKEN_SSL` somente se crossref:uses[uses-ssl,`ssl`] estiver definido. Se o port estiver marcado como BROKEN quando algumas condições forem atendidas, e tais condições puderem ser testadas somente após incluir o [.filename]#bsd.port.options.mk# ou [.filename]#bsd.port.pre.mk#, então essas variáveis ​​devem ser definidas mais tarde, em <>. ==== [[porting-order-depends]] == O Bloco de Dependências Este bloco é opcional. As variáveis ​​são: -* <> -* <> -* <> -* <> -* <> -* <> +* crossref:makefiles:[makefile-fetch_depends,`FETCH_DEPENDS`] +* crossref:makefiles:[makefile-extract_depends,`EXTRACT_DEPENDS`] +* crossref:makefiles:[makefile-patch_depends,`PATCH_DEPENDS`] +* crossref:makefiles:[makefile-build_depends,`BUILD_DEPENDS`] +* crossref:makefiles:[makefile-lib_depends,`LIB_DEPENDS`] +* crossref:makefiles:[makefile-run_depends,`RUN_DEPENDS`] * `TEST_DEPENDS` [[porting-order-flavors]] == Flavors Este bloco é opcional. -Comece esta seção com as definições de `FLAVORS`. Continue com as possíveis variáveis assistentes de Flavors. Veja <> para maiores informações. +Comece esta seção com as definições de `FLAVORS`. Continue com as possíveis variáveis assistentes de Flavors. Veja crossref:flavors[flavors-using,Usando FLAVORS] para maiores informações. Variáveis ​​de definição de construção não disponíveis como assistentes, usando `.if ${FLAVOR:U} == foo` devem ir em abaixo de suas respectivas seções. [[porting-order-uses]] == `USES` e `USE_x` Comece esta seção com a definição da variável `USES` e, em seguida, possíveis variáveis `USE_x`. -Mantenha as variáveis ​​relacionadas juntas. Por exemplo, se estiver usando a variável <>, coloque sempre as variáveis `GH_*` ​​logo após ela. +Mantenha as variáveis ​​relacionadas juntas. Por exemplo, se estiver usando a variável crossref:makefiles[makefile-master_sites-github,`USE_GITHUB`], coloque sempre as variáveis `GH_*` ​​logo após ela. [[porting-order-variables]] == Variáveis ​​Padrão [.filename]#bsd.port.mk# Este bloco de seção é para variáveis ​​que podem ser definidas em [.filename]#bsd.port.mk# que não pertencem a nenhum dos blocos de seção anteriores. A ordem não é importante, no entanto, tente manter variáveis ​​semelhantes juntas. Por exemplo, variáveis ​​`USERS` e `GROUPS`. Variáveis ​​de configuração `CONFIGURE__*_` e `_*__CONFIGURE`. Lista de arquivos e diretórios `PORTDOCS` e `PORTEXAMPLES`. [[porting-order-options]] == Opções e Assistentes -Se o port usa o <>, defina `OPTIONS_DEFINE` e `OPTIONS_DEFAULT`, então as outras variáveis `OPTIONS__*_`, depois as de descrições `_*__DESC`, e então os assistentes de opções. Tente e ordene todas essas variáveis alfabeticamente. +Se o port usa o crossref:makefiles[makefile-options,framework de opções], defina `OPTIONS_DEFINE` e `OPTIONS_DEFAULT`, então as outras variáveis `OPTIONS__*_`, depois as de descrições `_*__DESC`, e então os assistentes de opções. Tente e ordene todas essas variáveis alfabeticamente. [[porting-order-options-ex1]] .Exemplo de Ordenamento das Variáveis ​​de Opções [example] ==== As opções `FOO` e `BAR` não possuem uma descrição padrão, portanto, é necessário escrever uma. As outras opções já possuem em [.filename]#Mk/bsd.options.desc.mk# então escrever uma não é necessário. Opções `DOCS` e `EXAMPLES` usam os assistentes de destino para instalar seus arquivos, eles são mostrados aqui por completo, apesar de pertencerem a <>, então outras variáveis ​​e destinos podem ser inseridos antes deles. [.programlisting] .... OPTIONS_DEFINE= DOCS EXAMPLES FOO BAR OPTIONS_DEFAULT= FOO OPTIONS_RADIO= SSL OPTIONS_RADIO_SSL= OPENSSL GNUTLS OPTIONS_SUB= yes BAR_DESC= Enable bar support FOO_DESC= Enable foo support BAR_CONFIGURE_WITH= bar=${LOCALBASE} FOO_CONFIGURE_ENABLE= foo GNUTLS_CONFIGURE_ON= --with-ssl=gnutls OPENSSL_CONFIGURE_ON= --with-ssl=openssl post-install-DOCS-on: ${MKDIR} ${STAGEDIR}${DOCSDIR} cd ${WRKSRC}/doc && ${COPYTREE_SHARE} . ${STAGEDIR}${DOCSDIR} post-install-EXAMPLES-on: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} cd ${WRKSRC}/ex && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} .... ==== [[porting-order-rest]] == O Restante das Variáveis E então, o restante das variáveis ​​que não são mencionadas nos blocos anteriores. [[porting-order-targets]] == Os Targets Depois que todas as variáveis ​​são definidas, targets opcionais man:make[1] podem ser definidos. Mantenha `pre-_*_` antes de `post-_*_` e na mesma ordem em que as diferentes etapas são executadas: * `fetch` * `extract` * `patch` * `configure` * `build` * `install` * `test` [TIP] ==== Ao usar os assistentes de opções, os targets são classificados alfabeticamente, mas mantenha `_*_-on` antes do `_*_-off`. Quando também estiver usando o target principal, mantenha o target principal antes dos opcionais: [.programlisting] .... post-install: # install generic bits post-install-DOCS-on: # Install documentation post-install-X11-on: # Install X11 related bits post-install-X11-off: # Install bits that should be there if X11 is disabled .... ==== diff --git a/documentation/content/pt-br/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/pkg-files/_index.adoc similarity index 100% rename from documentation/content/pt-br/books/porters-handbook/pkg-files/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/pkg-files/_index.adoc diff --git a/documentation/content/pt-br/books/porters-handbook/plist/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/plist/_index.adoc similarity index 97% rename from documentation/content/pt-br/books/porters-handbook/plist/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/plist/_index.adoc index 7dc7c5c089..275ee64b41 100644 --- a/documentation/content/pt-br/books/porters-handbook/plist/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/plist/_index.adoc @@ -1,608 +1,608 @@ --- -title: Capítulo 8. Prácticas Avançadas de [.filename]#pkg-plist# +title: Capítulo 8. Prácticas Avançadas de pkg-plist prev: books/porters-handbook/flavors next: books/porters-handbook/pkg-files --- [[plist]] -= Prácticas Avançadas de [.filename]#pkg-plist# += Prácticas Avançadas de pkg-plist :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[plist-sub]] == Alterando o [.filename]#pkg-plist# Baseado em Variáveis Make -Alguns ports, particularmente os `p5-` ports, precisam mudar seus [.filename]#pkg-plist# dependendo de quais opções eles são configurados com (ou versão de `perl`, no caso de `p5-` ports). Para tornar isso fácil, todas as instâncias [.filename]#pkg-plist# de `%%OSREL%%`, `%%PERL_VER%%` e `%%PERL_VERSION%%` serão substituídas apropriadamente. O valor de `%%OSREL%%` é a revisão numérica do sistema operacional (por exemplo,`4.9`). `%%PERL_VERSION%%` e `%%PERL_VER%%` é o número completo da versão `perl` (por exemplo,`5.8.9`). Muitos outros `%%_VARS_%%` relacionados aos arquivos de documentação do port são descritos na <>. +Alguns ports, particularmente os `p5-` ports, precisam mudar seus [.filename]#pkg-plist# dependendo de quais opções eles são configurados com (ou versão de `perl`, no caso de `p5-` ports). Para tornar isso fácil, todas as instâncias [.filename]#pkg-plist# de `%%OSREL%%`, `%%PERL_VER%%` e `%%PERL_VERSION%%` serão substituídas apropriadamente. O valor de `%%OSREL%%` é a revisão numérica do sistema operacional (por exemplo,`4.9`). `%%PERL_VERSION%%` e `%%PERL_VER%%` é o número completo da versão `perl` (por exemplo,`5.8.9`). Muitos outros `%%_VARS_%%` relacionados aos arquivos de documentação do port são descritos na crossref:makefiles[install-documentation,seção relevante]. Para fazer outras substituições, defina `PLIST_SUB` com uma lista de pares `_VAR_=_VALOR_` e as instâncias de `%%_VAR_%%` serão substituídas por _VALOR_ no [.filename]#pkg-plist#. Por exemplo, se um port instalar muitos arquivos em um subdiretório específico da versão, use um placeholder para a versão de modo que o [.filename]#pkg-plist# não precise ser gerado novamente toda vez que o port é atualizado. Por exemplo: [.programlisting] .... OCTAVE_VERSION= ${PORTREVISION} PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} .... no [.filename]#Makefile# e use `%%OCTAVE_VERSION%%` onde quer que a versão apareça em [.filename]#pkg-plist#. Quando o port é atualizado, não será necessário editar dezenas (ou em alguns casos, centenas) de linhas no [.filename]#pkg-plist#. -Se os arquivos são instalados condicionalmente pelas opções definidas no port, a maneira usual de lidar com isso é prefixando as linhas [.filename]#pkg-plist# com `%%OPT%%` para linhas necessárias quando a opção está ativada ou `%%NO_OPT%%` quando a opção está desativada e adicionando `OPTIONS_SUB=yes` ao [.filename]#Makefile#. Veja <> para mais informações. +Se os arquivos são instalados condicionalmente pelas opções definidas no port, a maneira usual de lidar com isso é prefixando as linhas [.filename]#pkg-plist# com `%%OPT%%` para linhas necessárias quando a opção está ativada ou `%%NO_OPT%%` quando a opção está desativada e adicionando `OPTIONS_SUB=yes` ao [.filename]#Makefile#. Veja crossref:makefiles[options_sub,`OPTIONS_SUB`] para mais informações. Por exemplo, se houver arquivos que são instalados apenas quando a opção `X11` está ativada, e o [.filename]#Makefile# tem: [.programlisting] .... OPTIONS_DEFINE= X11 OPTIONS_SUB= yes .... No [.filename]#pkg-plist#, insira `%%X11%%` no início das linhas que serão instaladas apenas quando a opção estiver habilitada, assim: [.programlisting] .... %%X11%%bin/foo-gui .... Esta substituição será feita entre os targets `pre-install` e `do-install`, lendo a partir do [.filename]#PLIST# e escrevendo em [.filename]#TMPPLIST# (padrão:[.filename]##WRKDIR/.PLIST.mktmp##). Então, se o port gera o [.filename]#PLIST# na hora da compilação, faça isso em ou antes do `pre-install`. Além disso, se o port precisar editar o arquivo resultante, faça-o em `post-install` em um arquivo chamado [.filename]#TMPPLIST#. Outra maneira de modificar a lista de empacotamento de um port é baseada na configuração das variáveis `PLIST_FILES` e `PLIST_DIRS`. O valor de cada variável é considerado como uma lista de nomes de caminho para gravar no [.filename]#TMPPLIST# junto com conteúdo do [.filename]#PLIST#. Enquanto os nomes listados no `PLIST_FILES` e `PLIST_DIRS` estão sujeitos a substituição do `%%_VAR_%%` conforme descrito acima, é melhor usar o `${_VAR_}` diretamente. Exceto por isso, os nomes contidos no `PLIST_FILES` aparecerão inalterados na lista final de packing, enquanto o `@dir` será anexado aos nomes do `PLIST_DIRS`. Para fazer efeito, o `PLIST_FILES` e o `PLIST_DIRS` devem ser definidos antes que o [.filename]#TMPPLIST# seja escrito, isto é, no `pre-install` ou antes. De vez em quando, usar `OPTIONS_SUB` não é o suficiente. Nesses casos, adicionar uma `_TAG_` para `PLIST_SUB` dentro do [.filename]#Makefile# com um valor especial `@comment`, faz as ferramentas de pacote ignorar a linha. Por exemplo, se alguns arquivos são instalados apenas quando a opção `X11` está habilitada e a arquitetura é `i386`: [.programlisting] .... .include .if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386" PLIST_SUB+= X11I386="" .else PLIST_SUB+= X11I386="@comment " .endif .... [[plist-cleaning]] == Diretórios Vazios [[plist-dir-cleaning]] === Limpando Diretórios Vazios Ao ser desinstalado, um port deve remover os diretórios vazios que ele criou. A maioria desses diretórios são removidos automaticamente pelo man:pkg[8], mas para os diretórios criados fora do [.filename]#${PREFIX}#, ou diretórios vazios, mais alguns passos precisam ser feitos. Isso geralmente é realizando adicionando entradas `@dir` para esses diretórios.Os subdiretórios devem ser excluídos antes de excluir os diretórios pai. [.programlisting] .... [...] @dir /var/games/oneko/saved-games @dir /var/games/oneko .... [[plist-dir-empty]] === Criando Diretórios Vazios Os diretórios vazios criados durante a instalação do port precisam de atenção especial. Eles devem estar presentes quando o pacote é criado. Se eles não forem criados pelo código do port, crie-os no [.filename]#Makefile#: [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${PREFIX}/some/directory .... Adicione o diretório ao [.filename]#pkg-plist# como qualquer outro. Por exemplo: [.programlisting] .... @dir some/directory .... [[plist-config]] == Arquivos de Configuração Se o port instalar arquivos de configuração em [.filename]#PREFIX/etc# (ou em outro lugar) _não_ liste-os em [.filename]#pkg-plist#. Isso fará com que `pkg delete` remova os arquivos que foram cuidadosamente editados pelo usuário, e uma reinstalação irá eliminá-los. Em vez disso, instale arquivos de exemplo com uma extensão [.filename]#filename.sample#. A macro `@sample` automatiza isso, consulte <> para entender o que ela faz exatamente. Para cada arquivo de exemplo, adicione uma entrada no [.filename]#pkg-plist#: [.programlisting] .... @sample etc/orbit.conf.sample .... Se houver uma boa razão para não instalar um arquivo de configuração por padrão, liste apenas o nome do arquivo de exemplo em [.filename]#pkg-plist#, sem o `@sample` seguido por um espaço e adicione uma <> ressaltando que o usuário deve copiar e editar o arquivo antes que o software seja executado. [TIP] ==== Quando um port instala sua configuração em um subdiretório de [.filename]#${PREFIX}/etc#, usar `ETCDIR`, cujo padrão é `${PREFIX}/etc/${PORTNAME}`, pode ser substituído nos [.filename]#Makefile# dos ports se houver uma convenção para o port usar algum outro diretório. A macro `%%ETCDIR%%` será usado em seu lugar em [.filename]#pkg-plist#. ==== [NOTE] ==== Os arquivos de configuração de exemplo devem sempre ter o sufixo [.filename]#.sample#. Se, por algum motivo histórico, o uso do sufixo padrão não for possível ou se os arquivos de exemplo vierem de algum outro diretório, use esta construção: [.programlisting] .... @sample etc/orbit.conf-dist etc/orbit.conf .... ou [.programlisting] .... @sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf .... O formato é `@sample sample-file actual-config-file`. ==== [[plist-dynamic]] == Lista de Pacotes Estática versus Dinâmica Uma _lista de pacotes estáticos_ é uma lista de pacotes que está disponível na Coleção de Ports ou como [.filename]#pkg-plist# (com ou sem substituição de variável), ou embutido no [.filename]#Makefile# através do `PLIST_FILES` e do `PLIST_DIRS`. Mesmo se o conteúdo for gerado automaticamente por uma ferramenta ou um taget no Makefile _antes_ da inclusão na Coleção de Ports por um committer (por exemplo, usando `make makeplist`), isso ainda é considerado uma lista estática, já que é possível examiná-la sem ter que baixar ou compilar o distfile. Uma _lista de pacotes dinâmicos_ é uma lista de pacotes que é gerada no momento em que o port é compilado com base nos arquivos e diretórios que estão instalados. Não é possível examiná-lo antes que o código-fonte do aplicativo portado seja baixado e compilado, ou após executar um `make clean`. Embora o uso de listas de pacotes dinâmicos não seja proibido, os mantenedores devem usar listas de pacotes estáticos sempre que possível, já que isso permite aos usuários utilizar man:grep[1] nos de ports disponíveis para descobrir, por exemplo, qual port instala um determinado arquivo. Listas dinâmicas devem ser usadas principalmente para ports complexos onde a lista de pacotes muda drasticamente com base nos recursos opcionais do port (e assim manter uma lista de pacotes estática é impraticável), ou ports que alteram a lista de pacotes com base na versão do software dependente usado. Por exemplo, ports que geram documentos com Javadoc. [[plist-autoplist]] == Criação Automatizada da Lista de Pacotes Primeiro, verifique se o port está quase completo, faltando apenas o [.filename]#pkg-plist#. Executar o comando `make makeplist` irá mostrar um exemplo para o [.filename]#pkg-plist#. A saída do `makeplist` deve ser checada duas vezes quanto à correção, pois ela tenta adivinhar automaticamente algumas coisas e pode errar. Os arquivos de configuração do usuário devem ser instalados como [.filename]#filename.sample#, como é descrito em <>. O [.filename]#info/dir# não deve ser listado e entradas apropriadas [.filename]#install-info# devem ser adicionadas conforme a seção <>. Quaisquer bibliotecas instaladas pelo port devem ser listadas conforme especificado na seção <>. [[plist-autoplist-regex]] === Expansão do `PLIST_SUB` com Expressões Regulares As strings a serem substituídas às vezes precisam ser muito específicas para evitar substituições indesejadas. Esse é um problema comum com valores mais curtos. Para resolver este problema, para cada `PLACEHOLDER=value`, um `PLACEHOLDER_regex =regex` pode ser definido, com o _regex_ do `_value_` correspondendo mais precisamente. [[plist-autoplist-regex-ex1]] .Usando PLIST_SUB com Expressões Regulares [example] ==== Os ports Perl podem instalar arquivos dependentes da arquitetura em uma árvore específica. No FreeBSD para facilitar a portabilidade, esta árvore é chamada de `mach`. Por exemplo, um port que instala um arquivo cujo caminho contém `mach` poderia ter essa parte da sequência do caminho substituída pelos valores incorretos. Considere este [.filename]#Makefile#: [.programlisting] .... PORTNAME= Machine-Build DISTVERSION= 1 CATEGORIES= devel perl5 MASTER_SITES= CPAN PKGNAMEPREFIX= p5- MAINTAINER= perl@FreeBSD.org COMMENT= Building machine USES= perl5 USE_PERL5= configure PLIST_SUB= PERL_ARCH=mach .... Os arquivos instalados pelo port são: [.programlisting] .... /usr/local/bin/machine-build /usr/local/lib/perl5/site_perl/man/man1/machine-build.1.gz /usr/local/lib/perl5/site_perl/man/man3/Machine::Build.3.gz /usr/local/lib/perl5/site_perl/Machine/Build.pm /usr/local/lib/perl5/site_perl/mach/5.20/Machine/Build/Build.so .... Executar o `make makeplist` gera incorretamente: [.programlisting] .... bin/%%PERL_ARCH%%ine-build %%PERL5_MAN1%%/%%PERL_ARCH%%ine-build.1.gz %%PERL5_MAN3%%/Machine::Build.3.gz %%SITE_PERL%%/Machine/Build.pm %%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so .... Altere a linha `PLIST_SUB` do [.filename]#Makefile# para: [.programlisting] .... PLIST_SUB= PERL_ARCH=mach \ PERL_ARCH_regex=\bmach\b .... Agora o `make makeplist` gera corretamente: [.programlisting] .... bin/machine-build %%PERL5_MAN1%%/machine-build.1.gz %%PERL5_MAN3%%/Machine::Build.3.gz %%SITE_PERL%%/Machine/Build.pm %%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so .... ==== [[plist-keywords]] == Expandindo a Lista de Pacotes com Keywords Todas as keywords também podem ter argumentos opcionais entre parênteses. Os argumentos são owner, group e mode. Esse argumento é usado no arquivo ou diretório referenciado. Para alterar o dono, o grupo e o modo de um arquivo de configuração, use: [.programlisting] .... @sample(games,games,640) etc/config.sample .... Os argumentos são opcionais. Se apenas o grupo e o modo precisarem ser alterados, use: [.programlisting] .... @sample(,games,660) etc/config.sample .... [WARNING] ==== -Se uma keyword for utilizada em uma entrada de <>, ela precisa ser adicionada após o assistente: +Se uma keyword for utilizada em uma entrada de crossref:makefiles[makefile-options,opção], ela precisa ser adicionada após o assistente: [.programlisting] .... %%FOO%%@sample etc/orbit.conf.sample .... -Isso é porque os assistentes plist das opções são utilizados para comentar as linhas, e por isso eles precisam ser inseridos no início. Veja <> para maiores informações. +Isso é porque os assistentes plist das opções são utilizados para comentar as linhas, e por isso eles precisam ser inseridos no início. Veja crossref:makefiles[options_sub,`OPTIONS_SUB`] para maiores informações. ==== [[plist-keywords-desktop-file-utils]] === `@desktop-file-utils` -Irá executar o `update-desktop-database -q` após a instalação e desinstalação. _Nunca_ use diretamente, adicione <> ao [.filename]#Makefile#. +Irá executar o `update-desktop-database -q` após a instalação e desinstalação. _Nunca_ use diretamente, adicione crossref:uses[uses-desktop-file-utils,`USES=desktop-file-utils`] ao [.filename]#Makefile#. [[plist-keywords-fc]] === `@fc` _directory_ Adiciona uma entrada `@dir` para o diretório passado como um argumento, e executa `fc-cache -fs` nesse diretório após a instalação e desinstalação. [[plist-keywords-fcfontsdir]] === `@fcfontsdir` _directory_ Adiciona uma entrada `@dir` para o diretório passado como um argumento, e executa `fc-cache -fs`, `mkfontscale` e `mkfontdir` nesse diretório após a instalação e desinstalação. Além disso, na desinstalação, ele remove os arquivos de cache [.filename]#fonts.scale# e [.filename]#fonts.dir#, se estiverem vazios. Esta keyword é equivalente a adicionar o diretório <> e o diretório <>. [[plist-keywords-fontsdir]] === `@fontsdir` _directory_ Adiciona um entrada `@dir` para o diretório passado como um argumento, e executa `mkfontscale` e `mkfontdir` nesse diretório após a instalação e desinstalação. Além disso, na desinstalação, ele remove os arquivos de cache [.filename]#fonts.scale# e [.filename]#fonts.dir#, se estiverem vazios. [[plist-keywords-glib-schemas]] === `@glib-schemas` Executa `glib-compile-schemas` na instalação e desinstalação. [[plist-keywords-info]] === `@info` _file_ -Adiciona o arquivo passado como argumento ao plist e atualiza o índice do documento info na instalação e desinstalação. Além disso, ele remove o índice se estiver vazio na desinstalação. Isso nunca deve ser usado manualmente, mas sempre `INFO`. Veja <> para maiores informações. +Adiciona o arquivo passado como argumento ao plist e atualiza o índice do documento info na instalação e desinstalação. Além disso, ele remove o índice se estiver vazio na desinstalação. Isso nunca deve ser usado manualmente, mas sempre `INFO`. Veja crossref:makefiles[makefile-info,Arquivos de Informação] para maiores informações. [[plist-keywords-kld]] === `@kld` _directory_ Executa o `kldxref` no diretório na instalação e desinstalação. Além disso, na desinstalação, ele removerá o diretório se estiver vazio. [[plist-keywords-rmtry]] === `@rmtry` _file_ O arquivo será removido na desinstalação, e não dará um erro se o arquivo não estiver lá. [[plist-keywords-sample]] === `@sample` __file__[__file__] Isso é usado para lidar com a instalação de arquivos de configuração, através de arquivos de exemplo empacotados com o pacote. O arquivo "atual", não-amostra, ou é o segundo nome do arquivo, se presente, ou o primeiro nome de arquivo sem a extensão [.filename]#.sample#. Isso faz três coisas. Primeiro, adiciona o primeiro arquivo passado como argumento, o arquivo de exemplo, ao plist. Então, na instalação, se o arquivo real não for encontrado, copia o arquivo de exemplo para o arquivo real. E, finalmente, na desinstalação, remove o arquivo atual se ele não tiver sido modificado. Veja <> para maiores informações. [[plist-keywords-shared-mime-info]] === `@shared-mime-info` _directory_ Executa `update-mime-database` no diretório na instalação e desinstalação. [[plist-keywords-shell]] === `@shell` _file_ Adiciona o arquivo passado como argumento ao plist. Na instalação, adiciona o caminho completo do _file_ em [.filename]#/etc/shells#, certificando-se que não é adicionado duas vezes. Na desinstalação, remove-o de [.filename]#/etc/shells#. [[plist-keywords-terminfo]] === `@terminfo` Não use sozinho. Se o port for instalar arquivos [.filename]#*.terminfo#, adicione <> no seu [.filename]#Makefile#. Na instalação e desinstalação, se o `tic` estiver presente, atualize o [.filename]#${PREFIX}/shared/misc/terminfo.db# a partir dos arquivos [.filename]#*.terminfo# disponíveis em [.filename]#${PREFIX}/shared/misc#. [[plist-keywords-base]] === Keywords Básicas Existem algumas keywords que são codificadas e documentadas em man:pkg-create[8]. Por uma questão de completude, elas também estão documentadas aqui. [[plist-keywords-base-empty]] ==== `@` [__file__] A keyword vazia é um espaço reservado para ser usado quando o proprietário, grupo ou modo do arquivo precisam ser alterados. Por exemplo, para definir o grupo de um arquivo como `games` e adicionar o bit setgid, adicione: [.programlisting] .... @(,games,2755) sbin/daemon .... [[plist-keywords-base-exec]] ==== `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_ Executa o _command_ como parte do processo de instalação ou desinstalação. `@preexec` _command_:: Executar o _command_ como parte dos scripts [.filename]#pre-install#. `@postexec` _command_:: Executar o _command_ como parte dos scripts [.filename]#post-install#. `@preunexec` _command_:: Executar o _command_ como parte dos scripts [.filename]#pre-deinstall#. `@postunexec` _command_:: Executar o _command_ como parte dos scripts [.filename]#post-deinstall#. E se o _command_ contém qualquer uma dessas sequências em algum lugar, elas são expandidas em linha. Para estes exemplos, assuma que `@cwd` está configurado para [.filename]#/usr/local# e o último arquivo extraído foi [.filename]#bin/emacs#. `%F`:: Expandir para o último nome de arquivo extraído (conforme especificado). No caso do exemplo [.filename]#bin/emacs#. `%D`:: Expandir para o prefixo do diretório atual, como definido no `@cwd`. No caso do exemplo [.filename]#/usr/local#. `%B`:: Expandir para o nome de base do nome completo do arquivo, ou seja, o prefixo do diretório atual mais o último arquivo, menos o nome do arquivo final. No exemplo, isso seria [.filename]#/usr/local/bin#. `%f`:: Expandir para a parte do nome do arquivo do nome totalmente qualificado, ou o inverso de `%B`. No caso do exemplo, [.filename]#emacs#. [IMPORTANT] ==== Essas keywords estão aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível. Elas _não devem_ ser abusadas para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução. ==== [[plist-keywords-base-mode]] ==== `@mode` _mode_ Define a permissão padrão para todos os arquivos extraídos posteriormente para _mode_. O formato é o mesmo usado por man:chmod[1]. Use sem um argumento para voltar às permissões padrão (modo do arquivo enquanto estava sendo empacotado). [IMPORTANT] ==== Este deve ser um modo numérico, como `644`, `4755` ou `600`. Não pode ser um modo relativo como `u+s`. ==== [[plist-keywords-base-owner]] ==== `@owner` _user_ Define a propriedade padrão para todos os arquivos subsequentes para _user_. Use sem um argumento para voltar à propriedade padrão (`root`). [[plist-keywords-base-group]] ==== `@group` _group_ Define a propriedade de grupo padrão para todos os arquivos subsequentes para _group_. Use sem um argumento para retornar à propriedade do grupo padrão (`wheel`). [[plist-keywords-base-comment]] ==== `@comment` _string_ Esta linha é ignorada no momento de empacotar. [[plist-keywords-base-dir]] ==== `@dir` _directory_ Declara o nome do diretório. Por padrão, os diretórios criados sob `PREFIX` por uma instalação de pacote são automaticamente removidos. Use isto quando um diretório vazio sob `PREFIX` precisa ser criado ou quando o diretório precisa ter proprietário, grupo ou modo não padrão. Diretórios fora de `PREFIX` precisam ser registrados. Por exemplo, [.filename]#/var/db/${PORTNAME}# precisa ter uma entrada `@dir` enquanto [.filename]#${PREFIX}/shared/${PORTNAME}# não, se contiver arquivos ou usar o proprietário, grupo e modo padrão. [[plist-keywords-base-exec-deprecated]] ==== `@exec` _command_, `@unexec` _command_ (Descontinuado) Executa o _command_ como parte do processo de instalação ou desinstalação. Por favor, use <> no lugar. [[plist-keywords-base-dirrm]] ==== `@dirrm` _directory_ (Descontinuado) Declara o nome do diretório a ser excluído na desinstalação. Por padrão, os diretórios criados sob `PREFIX` por uma instalação de pacote são excluídos quando o pacote é desinstalado. [[plist-keywords-base-dirrmtry]] ==== `@dirrmtry` _directory_ (Descontinuado) Declara o nome do diretório a ser removido, como para a keyword `@dirrm`, mas não emite um aviso se o diretório não puder ser removido. [[plist-keywords-creating-new]] === Criando Novas Keywords Os arquivos da lista de pacotes podem ser estendidos por keywords definidas no diretório [.filename]#${PORTSDIR}/Keywords#. As configurações de cada keyword são armazenadas em um arquivo UCL chamado [.filename]#keyword.ucl#. O arquivo deve conter pelo menos uma destas seções: * `attributes` * `action` * `pre-install` * `post-install` * `pre-deinstall` * `post-deinstall` * `pre-upgrade` * `post-upgrade` [[plist-keywords-attributes]] ==== `attributes` Altera o dono, grupo ou modo usado pela keyword. Contém uma matriz associativa em que as chaves possíveis são `owner`, `group` e `mode`. Os valores são, respectivamente, um nome de usuário, um nome de grupo e um modo de arquivo. Por exemplo: [.programlisting] .... attributes: { owner: "games", group: "games", mode: 0555 } .... [[plist-keywords-action]] ==== `action` Define o que acontece com o parâmetro da keyword. Contém uma matriz onde os valores possíveis são: `setprefix`:: Define o prefixo para as próximas entradas do plist. `dir`:: Registra um diretório para ser criado na instalação e removido na desinstalação. `dirrm`:: Registra um diretório a ser excluído na desinstalação. Descontinuado. `dirrmtry`:: Registra um diretório para tentar deletar na desinstalação. Descontinuado. `file`:: Registra um arquivo. `setmode`:: Define o modo para as próximas entradas do plist. `setowner`:: Define o dono para as próximas entradas do plist. `setgroup`:: Define o grupo para as próximas entradas do plist. `comment`:: Não faz nada, é o equivalente a não entrar em uma seção `action`. `ignore_next`:: Ignora a próxima entrada no plist. [[plist-keywords-arguments]] ==== `arguments` Se definido para `true`, adiciona manipulação de argumentos, dividindo toda a linha, `%@`, em argumentos numerados,`%1`, `%2`, e assim por diante. Por exemplo, para esta linha: [.programlisting] .... @foo some.content other.content .... `%1` e `%2` irão conter: [.programlisting] .... some.content other.content .... Também afeta como a entrada <> funciona. Quando há mais de um argumento, o número do argumento deve ser especificado. Por exemplo: [.programlisting] .... actions: [file(1)] .... [[plist-keywords-pre-post]] ==== `pre-install`, `post-install`, `pre-deinstall`, `post-deinstall`, `pre-upgrade`, `post-upgrade` Essas keywords contêm um script man:sh[1] a ser executado antes ou depois da instalação, desinstalação, ou atualização do pacote. Além do habitual placeholder `@exec %foo` descrito em <>, há um novo `%@`, que representa o argumento da keyword. [[plist-keywords-examples]] ==== Exemplos de Keywords Customizadas [[plist-keywords-fc-example]] .Exemplo de uma Keyword `@dirrmtryecho` [example] ==== Esta keyword faz duas coisas, adiciona uma linha `@dirrmtry _directory_` na lista de empacotamento, e escreve no log quando o diretório é removido ao desinstalar o pacote. [.programlisting] .... actions: [dirrmtry] post-deinstall: <> em vez de sobrescrever o arquivo. [[porting-wrkdirprefix]] == `WRKDIRPREFIX` Certifique-se de que o port honre a variável `WRKDIRPREFIX`. A maioria dos ports não precisa se preocupar com isso. Em particular, quando se refere a uma variável `WRKDIR` de outro port, observe que o local correto é [.filename]#WRKDIRPREFIXPORTSDIR/subdir/name/work# e não [.filename]#PORTSDIR/subdir/name/work# ou [.filename]#.CURDIR/../../subdir/name/work# ou algo assim. Além disso, se definir `WRKDIR`, certifique-se de adicionar `${WRKDIRPREFIX}${.CURDIR}` na frente. [[porting-versions]] == Diferenciando Sistemas Operacionais e Versões de OS Alguns códigos precisam de modificações ou compilação condicional com base na versão do FreeBSD Unix em que ele está sendo executado. A maneira preferida de distinguir as versões do FreeBSD é usar as macros {freebsd-version} e {freebsd} definidas em https://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup[sys/param.h]. Se este arquivo não estiver incluído, adicione o código, [.programlisting] .... #include .... para o lugar adequado no arquivo [.filename]#.c#. {freebsd} é definido em todas as versões do FreeBSD para seu principal número de versão. Por exemplo, no FreeBSD 9.x, {freebsd} é definido para `9`. [.programlisting] .... #if __FreeBSD__ >= 9 # if __FreeBSD_version >= 901000 /* 9.1+ release specific code here */ # endif #endif .... -Uma lista completa de valores `__FreeBSD_version` está disponível em <>. +Uma lista completa de valores `__FreeBSD_version` está disponível em crossref:versions[versions, Valores `__FreeBSD_version`]. [[dads-after-port-mk]] == Escrevendo Algo Depois do [.filename]#bsd.port.mk# Não escreva nada depois da linha `.include `. Isso geralmente pode ser evitado incluindo [.filename]#bsd.port.pre.mk# em algum lugar no meio do [.filename]#Makefile# e [.filename]#bsd.port.post.mk# no fim. [IMPORTANT] ==== Inclua o par [.filename]#bsd.port.pre.mk#/[.filename]#bsd.port.post.mk# ou apenas [.filename]#bsd.port.mk#; não misture o uso dos dois. ==== [.filename]#bsd.port.pre.mk# define apenas algumas variáveis, que podem ser usadas em testes no [.filename]#Makefile#, [.filename]#bsd.port.post.mk# define o restante. Aqui estão algumas variáveis ​​importantes definidas no arquivo [.filename]#bsd.port.pre.mk# (esta não é a lista completa, por favor leia [.filename]#bsd.port.mk# para a lista completa). [.informaltable] [cols="1,1", frame="none", options="header"] |=== | Variável | Descrição |`ARCH` |A arquitetura retornada por `uname -m` (por exemplo, `i386`) |`OPSYS` |O tipo de sistema operacional, conforme retornado por `uname -s` (por exemplo, `FreeBSD`) |`OSREL` |A versão de lançamento do sistema operacional (por exemplo, `2.1.5` ou `2.2.7`) |`OSVERSION` |A versão numérica do sistema operacional; o mesmo que <>. |`LOCALBASE` |A base da árvore "local" (por exemplo, `/usr/local`) |`PREFIX` |Onde o port se instala (veja <>). |=== [NOTE] ==== Quando `MASTERDIR` for necessário, sempre o defina antes de incluir o [.filename]#bsd.port.pre.mk#. ==== Aqui estão alguns exemplos de coisas que podem ser adicionadas depois do [.filename]#bsd.port.pre.mk#: [.programlisting] .... # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif .... Sempre use tab em vez de espaços após o argumento `BROKEN=`. [[dads-sh-exec]] == Uso de Declarações `exec` em Wrapper Scripts Se o port instalar um script shell cuja finalidade é executar outro programa, e se a execução desse programa for a última ação executada pelo script, certifique-se de executar o programa usando a função `exec`, por exemplo: [.programlisting] .... #!/bin/sh exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@" .... A declaração de `exec` substitui o processo do shell pelo programa especificado. E se `exec` for omitido, o processo do shell permanece na memória enquanto o programa está sendo executado e consome desnecessariamente recursos do sistema. [[dads-rational]] == Faça as Coisas Racionalmente O [.filename]#Makefile# deve fazer as coisas de uma maneira simples e razoável. Tornar algumas linhas mais curtas ou mais legíveis é sempre melhor. Exemplos incluem usar um construtor `.if` do make em vez de um construtor `if` do shell, não redefinir `do-extract` se redefinir `EXTRACT*` é o suficiente e usar `GNU_CONFIGURE` ao invés de `CONFIGURE_ARGS += --prefix=${PREFIX}`. Se um monte de código novo é necessário para fazer algo, já pode haver uma implementação dele em [.filename]#bsd.port.mk#. Embora seja difícil de ler, há muitos problemas aparentemente difíceis para os quais [.filename]#bsd.port.mk# já fornece uma solução simples. [[dads-cc]] == Respeite Ambos `CC` e `CXX` O port deve respeitar tanto `CC` e `CXX`. O que queremos dizer com isso é que o port não deve definir os valores dessas variáveis ​​absolutamente, sobrepondo os valores existentes; em vez disso, pode anexar quaisquer valores necessários aos valores existentes. Isso é para que as opções de build que afetam todos os ports possam ser definidas globalmente. Se o port não respeitar essas variáveis, por favor adicione `NO_PACKAGE=ignores either cc or cxx` ao [.filename]#Makefile#. Aqui está um exemplo do [.filename]#Makefile# respeitando ambos `CC` e `CXX`. Note o `?=`: [.programlisting] .... CC?= gcc .... [.programlisting] .... CXX?= g++ .... Aqui está um exemplo que não respeita nem `CC` nem `CXX`: [.programlisting] .... CC= gcc .... [.programlisting] .... CXX= g++ .... Ambos `CC` e `CXX` podem ser definidos em sistemas FreeBSD no arquivo [.filename]#/etc/make.conf#. O primeiro exemplo define um valor se não foi definido anteriormente no arquivo [.filename]#/etc/make.conf#, preservando quaisquer definições de todo o sistema. O segundo exemplo atrapalha qualquer coisa previamente definida. [[dads-cflags]] == Respeite `CFLAGS` O port deve respeitar a variável `CFLAGS`. O que queremos dizer com isso é que o port não deve definir o valor dessa variável absolutamente, substituindo o valor existente. Em vez disso, pode anexar quaisquer valores necessários ao valor existente. Isso é para que as opções de build que afetam todos os ports possam ser definidas globalmente. Se isso não acontecer, por favor adicione `NO_PACKAGE=ignores cflags` ao [.filename]#Makefile#. Aqui está um exemplo de [.filename]#Makefile# respeitando `CFLAGS`. Note o `+=`: [.programlisting] .... CFLAGS+= -Wall -Werror .... Aqui está um exemplo que não respeita `CFLAGS`: [.programlisting] .... CFLAGS= -Wall -Werror .... `CFLAGS` são definidas em sistemas FreeBSD no arquivo [.filename]#/etc/make.conf#. O primeiro exemplo acrescenta flags adicionais para a variável `CFLAGS`, preservando quaisquer definições de todo o sistema. O segundo exemplo atrapalha qualquer coisa previamente definida. Remove flags de otimização do [.filename]#Makefile# de terceiros. O sistema de variáveis `CFLAGS` contém flags de otimização de todo o sistema. Um exemplo de um [.filename]#Makefile# não modificado: [.programlisting] .... CFLAGS= -O3 -funroll-loops -DHAVE_SOUND .... Usando flags de otimização do sistema, o [.filename]#Makefile# seria semelhante a este exemplo: [.programlisting] .... CFLAGS+= -DHAVE_SOUND .... [[dads-verbose-logs]] == Logs de Compilação Detalhados Faz com que o sistema de build dos ports exiba todos os comandos executados durante o estágio de build. Os registros de build completos são cruciais para depurar problemas de ports. Exemplo de log de compilação não informativo (ruim): [.programlisting] .... CC source1.o CC source2.o CCLD someprogram .... Exemplo de log de compilação detalhado (bom): [.programlisting] .... cc -O2 -pipe -I/usr/local/include -c -o source1.o source1.c cc -O2 -pipe -I/usr/local/include -c -o source2.o source2.c cc -o someprogram source1.o source2.o -L/usr/local/lib -lsomelib .... Alguns sistemas de build, como o CMake, ninja e GNU configure são configurados para registro detalhado pelo framework do ports. Em outros casos, os ports podem precisar de ajustes individuais. [[dads-feedback]] == Feedback Envie mudanças aplicáveis e correções ​​para o mantenedor upstream para inclusão na próxima versão do código. Isso torna a atualização para a próxima versão muito mais fácil. [[dads-readme]] == [.filename]#README.html# [.filename]#README.html# não faz parte do port, mas é gerado com o comando `make readme`. Não inclua este arquivo em patches ou commits. [NOTE] ==== Se o comando `make readme` falhar, certifique-se de que o valor padrão de `ECHO_MSG` não tenha sido modificado pelo port. ==== [[dads-noinstall]] == Marcando um Port não Instalável com a variável `BROKEN`, `FORBIDDEN` ou `IGNORE` Em certos casos, os usuários devem ser impedidos de instalar um port. Existem várias variáveis ​​que podem ser usadas no [.filename]#Makefile# de um port para informar ao usuário que o port não pode ser instalado. O valor dessas variáveis ​​make será o motivo que é mostrado aos usuários do porque o port se recusa a se instalar. Por favor, use a variável correta. Cada variável transmite significados radicalmente diferentes, tanto para usuários quanto para sistemas automatizados que dependem do [.filename]#Makefile#, assim como <>, <> e <>. [[dads-noinstall-variables]] === Variáveis * `BROKEN` é reservada para ports que atualmente não compilam, instalam, desinstalam ou que não são executados corretamente. Use-o para ports em que o problema é considerado temporário. + Se instruído, o cluster de build ainda tentará compilar eles para ver se o problema subjacente foi resolvido. (No entanto, em geral, o cluster é executado sem isso.) + Por exemplo, use `BROKEN` quando um port: ** não compila ** falha em sua configuração ou no processo de instalação ** instala arquivos fora do [.filename]#${PREFIX}# ** não remove todos os seus arquivos corretamente após a desinstalação (no entanto, pode ser aceitável, e desejável, que o port deixe arquivos modificados pelo usuário por fora do port) ** tem problemas em tempo de execução em sistemas nos quais é necessário que ele seja executado corretamente. * A variável `FORBIDDEN` é usada para ports que contêm uma vulnerabilidade de segurança ou causam grande preocupação em relação à segurança de um sistema FreeBSD com um determinado port instalado (por exemplo, um programa de confiança inseguro ou um programa que fornece serviços facilmente exploráveis). Marcar ports como `FORBIDDEN` assim que um determinado software tiver uma vulnerabilidade e não houver atualização liberada. Idealmente, atualize os ports o mais rápido possível quando uma vulnerabilidade de segurança for descoberta para reduzir o número de hosts vulneráveis ​​do FreeBSD (gostamos de ser conhecidos pela segurança), mas às vezes há um intervalo de tempo entre a divulgação de uma vulnerabilidade e uma versão atualizada do software vulnerável. Não marque um port como `FORBIDDEN` por qualquer outro motivo que não seja segurança. * A variável `IGNORE` é reservada para ports que não devem ser compilados por algum outro motivo. Use-a para ports em que o problema é considerado estrutural. O cluster de build não criará, sob nenhuma circunstância, ports marcados com a variável `IGNORE`. Por exemplo, use `IGNORE` quando um port: ** não funciona na versão instalada do FreeBSD ** tem um distfile que não pôde ser obtido automaticamente devido a restrições de licenciamento ** não funciona com algum outro port atualmente instalado (por exemplo, o port depende do package:www/apache20[] mas package:www/apache22[] está instalado) + [NOTE] ==== Se um port entrar em conflito com um port que está atualmente instalado (por exemplo, se eles instalam um arquivo no mesmo local que executa uma função diferente), <>. `CONFLICTS` ajustará `IGNORE` por si próprio. ==== [[dads-noinstall-notes]] === Notas de Implementação Não coloque os valores de `BROKEN`, `IGNORE` e variáveis ​​relacionadas entre aspas. Devido à forma como a informação é mostrada ao usuário, o texto das mensagens para cada variável é diferente: [.programlisting] .... BROKEN= fails to link with base -lcrypto .... [.programlisting] .... IGNORE= unsupported on recent versions .... resultando nesta saída a partir do comando `make describe`: [.programlisting] .... ===> foobar-0.1 is marked as broken: fails to link with base -lcrypto. .... [.programlisting] .... ===> foobar-0.1 is unsupported on recent versions. .... [[dads-arch]] == Considerações Arquitetônicas [[dads-arch-general]] === Notas Gerais sobre Arquiteturas O FreeBSD roda em muito mais arquiteturas de processador do que apenas as conhecidas baseadas em x86. Alguns ports possuem restrições específicas para uma ou mais dessas arquiteturas. Para a lista de arquiteturas suportadas, execute: [.programlisting] .... cd ${SRCDIR}; make targets .... Os valores são mostrados no formato `TARGET`/`TARGET_ARCH`. O makevar `ARCH` somente leitura do ports é configurado com base no valor de `TARGET_ARCH`. Os [.filename]##Makefile##s dos Ports devem testar o valor deste Makevar. [[dads-arch-neutral]] === Marcando um Port como de Arquitetura Neutra Os ports que não possuem requisitos ou arquivos dependentes de arquitetura são identificados com `NO_ARCH=yes`. [NOTE] ==== `NO_ARCH` pretende indicar que não há necessidade de compilar um pacote para cada uma das arquiteturas suportadas. O objetivo é reduzir a quantidade de recursos gastos na compilação e distribuição de pacotes, como largura de banda de rede e espaço em disco em mirrors e na mídia de distribuição. Atualmente, entretanto, nossa infraestrutura de pacotes (por exemplo, gerenciadores de pacotes, mirrors e compiladores de pacotes) não estão configurados para se beneficiar totalmente do `NO_ARCH`. ==== [[dads-arch-ignore]] === Marcando um port para ser ignorado apenas em determinadas arquiteturas * Para marcar um port com `IGNORE` apenas em determinadas arquiteturas, existem duas outras variáveis ​​de conveniência que irão setar automaticamente `IGNORE`: `ONLY_FOR_ARCHS` e `NOT_FOR_ARCHS`. Exemplos: + [.programlisting] .... ONLY_FOR_ARCHS= i386 amd64 .... + [.programlisting] .... NOT_FOR_ARCHS= ia64 sparc64 .... + Uma mensagem de `IGNORE` customizada pode ser definida usando as variáveis `ONLY_FOR_ARCHS_REASON` e `NOT_FOR_ARCHS_REASON`. É possível definir entradas por arquitetura com as variáveis `ONLY_FOR_ARCHS_REASON_ARCH` e `NOT_FOR_ARCHS_REASON_ARCH`. [[dads-arch-i386]] === Unknown Title! * Se um port baixar e instalar binários i386, defina a variável `IA32_BINARY_PORT`. Se esta variável estiver definida,[.filename]#/usr/lib32# deve estar presente para versões IA32 de bibliotecas e o kernel deve suportar compatibilidade com IA32. Se uma dessas duas dependências não forem satisfeitas, `IGNORE` será definido automaticamente. [[dads-arch-cluster]] === Considerações Específicas do Cluster * Alguns ports tentam se ajustar à máquina exata em que estão sendo compilados, definindo `-march=native` para o compilador. Isso deve ser evitado: liste-o em uma opção desativada por padrão ou exclua-o completamente. + Caso contrário, o pacote padrão produzido pelo cluster de compilação pode não rodar em todas as máquinas desse `ARCH`. [[dads-deprecated]] == Marcando um Port para Remoção com `DEPRECATED` ou `EXPIRATION_DATE` Lembre-se que `BROKEN` e `FORBIDDEN` devem ser usados ​​como um recurso temporário se um port não estiver funcionando. Ports permanentemente quebrados serão removidos da árvore por completo. Quando fizer sentido, os usuários podem ser avisados ​​sobre uma remoção de port pendente com as variáveis `DEPRECATED` e `EXPIRATION_DATE`. A primeira é uma string que indica porque o port está programado para remoção; a segunda é uma string no formato ISO 8601 (YYYY-MM-DD). Ambos serão mostrados ao usuário. É possível definir a variável `DEPRECATED` sem uma `EXPIRATION_DATE` (por exemplo, recomendando uma versão mais nova do port), mas o contrário não faz sentido. Não existe uma política definida sobre o tempo de aviso a ser dado. A prática atual parece ser de um mês para problemas relacionados à segurança e dois meses para problemas de compilação. Isso também dá a algum interessado um pouco de tempo para resolver os problemas. [[dads-dot-error]] == Evite o Uso do Construtor `.error` A maneira correta de um [.filename]#Makefile# sinalizar que o port não pode ser instalado devido a algum fator externo (por exemplo, o usuário especificou uma combinação ilegal de opções de compilação) é definir um valor não vazio para `IGNORE`. Este valor será formatado e mostrado ao usuário pelo comando `make install`. -É um equívoco comum usar `.error` para esse propósito. O problema com isso é que muitas ferramentas automatizadas que funcionam com a árvore de ports falharão nessa situação. A ocorrência mais comum disso é encontrada ao tentar construir o arquivo [.filename]#/usr/ports/INDEX# (Veja <>). No entanto, comandos ainda mais triviais, como `make maintainer` também irão falhar neste cenário. E Isto não é aceitável. +É um equívoco comum usar `.error` para esse propósito. O problema com isso é que muitas ferramentas automatizadas que funcionam com a árvore de ports falharão nessa situação. A ocorrência mais comum disso é encontrada ao tentar construir o arquivo [.filename]#/usr/ports/INDEX# (Veja crossref:testing[make-describe, Executando `make describe`]). No entanto, comandos ainda mais triviais, como `make maintainer` também irão falhar neste cenário. E Isto não é aceitável. [[dot-error-breaks-index]] .Como Evitar o Uso de `.error` [example] ==== O primeiro dos próximos dois trechos de [.filename]#Makefile# irá fazer o `make index` falhar, enquanto o segundo não: [.programlisting] .... .error "option is not supported" .... [.programlisting] .... IGNORE=option is not supported .... ==== [[dads-sysctl]] == Uso de [.filename]#sysctl# O uso de [.filename]#sysctl# é desencorajado, exceto nos targets. Isso porque ele seria processado na execução de qualquer `makevar`, como os usados durante um `make index`, e assim teria que executar o comando, retardando ainda mais esse processo. Use apenas man:sysctl[8] através de `SYSCTL`, pois contém o caminho completo e pode ser modificado, se alguém tiver uma necessidade especial. [[dads-rerolling-distfiles]] == Atualizando Distfiles De vez em quando os autores de software alteram o conteúdo dos distfiles liberados sem alterar o nome do arquivo. Verifique se as alterações são oficiais e se foram realizadas pelo autor. Já aconteceu no passado em que o distfile foi silenciosamente alterado nos servidores de download com a intenção de prejudicar ou comprometer a segurança do usuário final. Coloque o antigo distfile de lado, faça o download do novo, descompacte-o e compare o conteúdo com o man:diff[1]. Se não houver nada suspeito, atualize o [.filename]#distinfo#. [IMPORTANT] ==== Certifique-se de resumir as diferenças no log do PR e do commit, para que outras pessoas saibam que nada de ruim aconteceu. ==== Contate os autores do software e confirme as alterações com eles. [[dads-use-posix-standards]] == Uso de Padrões POSIX Os ports do FreeBSD geralmente esperam conformidade com POSIX. Alguns softwares e sistemas de compilação fazem suposições baseadas em um sistema operacional ou ambiente específico que pode causar problemas quando usado em um port. Não use [.filename]#/proc# se houver outras maneiras de obter as informações. Por exemplo, `setprogname(argv[0])` dentro de `main()` e depois man:getprogname[3] para saber o nome do executável. Não confie em comportamento não documentado pelo POSIX. Não registre timestamps no caminho crítico do aplicativo se ele também funcionar sem. Obter registros de timestamps pode ser lento, dependendo da precisão dos registros de timestamp no SO. Se os timestamps forem realmente necessários, determine o quão precisos eles devem ser e use uma API documentada para fornecer a precisão necessária. Um número razoável de syscalls simples (por exemplo man:gettimeofday[2], man:getpid[2]) são muito mais rápidos no Linux(TM) do que em qualquer outro sistema operacional, devido ao armazenamento em cache e às otimizações de desempenho do vsyscall. Não confie que seus custos sejam baratos em aplicativos de desempenho crítico. Em geral, tente evitar as syscalls se possível. Não confie no comportamento de sockets específicos do Linux(TM). Em particular, os tamanhos padrão do buffer de socket são diferentes (chamadas man:setsockopt[2] com `SO_SNDBUF` e `SO_RCVBUF`, e enquanto o man:send[2] do Linux(TM)'s bloqueia quando o buffer do socket está cheio, o do FreeBSD falhará e definirá `ENOBUFS` no errno). Se for necessário depender de um comportamento não padrão, encapsule-o adequadamente em uma API genérica, verifique o comportamento no estágio de configuração e pare se ele estiver ausente. Verifique as https://www.freebsd.org/cgi/man.cgi[páginas de manual] para ver se a função usada é uma interface POSIX (na seção "STANDARDS" da página de manual). Não assuma que [.filename]#/bin/sh# é o bash. Certifique-se de que uma linha de comando passada para man:system[3] irá funcionar com um shell compatível com POSIX. Uma lista de bashismos comum está disponível https://wiki.ubuntu.com/DashAsBinSh[aqui]. Verifique se os cabeçalhos estão incluídos no POSIX ou da maneira recomendada na página do manual. Por exemplo,[.filename]#sys/types.h# é muitas vezes esquecido, o que não é tanto um problema para o Linux(TM) como é para o FreeBSD. [[dads-misc]] == Miscelânea Sempre verifique duas vezes os arquivos [.filename]#pkg-descr# e [.filename]#pkg-plist#. Se estiver revisando um port e uma melhor formulação puder ser alcançada, faça isso. Não faça mais cópias da Licença GNU General Public License em nosso sistema. Obrigado. Por favor, tenha cuidado ao notar quaisquer questões legais! Não nos deixe distribuir software ilegalmente! diff --git a/documentation/content/pt-br/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/porting-samplem/_index.adoc similarity index 97% rename from documentation/content/pt-br/books/porters-handbook/porting-samplem/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/porting-samplem/_index.adoc index dbcd834f8d..3a6e02ebdf 100644 --- a/documentation/content/pt-br/books/porters-handbook/porting-samplem/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/porting-samplem/_index.adoc @@ -1,138 +1,138 @@ --- -title: Capítulo 14. Um Exemplo de [.filename]#Makefile# +title: Capítulo 14. Um Exemplo de Makefile prev: books/porters-handbook/porting-dads next: books/porters-handbook/order --- [[porting-samplem]] -= Um Exemplo de [.filename]#Makefile# += Um Exemplo de Makefile :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 14 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Aqui está um exemplo de [.filename]#Makefile# que pode ser usado para criar um novo port. Certifique-se de remover todos os comentários extras (entre colchetes). O formato apresentado é o recomendado para ordenar variáveis, linhas vazias entre seções e assim por diante. Esse formato é projetado para que as informações mais importantes sejam fáceis de serem localizadas. Recomendamos usar o <> para verificar o [.filename]#Makefile#. [.programlisting] .... [the header...just to make it easier for us to identify the ports.] # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by SVN when it is committed to our repository. If upgrading a port, do not alter this line back to "$FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $". SVN deals with it automatically.] [section to describe the port itself and the master site - PORTNAME and PORTVERSION or the DISTVERSION* variables are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi DISTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if not using MASTER_SITE_* macros] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications PKGNAMEPREFIX= ja- DISTNAME= xdvi-pl18 [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [If the distributed patches were not made relative to ${WRKSRC}, this may need to be tweaked] PATCH_DIST_STRIP= -p1 [maintainer; *mandatory*! This is the person who is volunteering to handle port updates, build breakages, and to whom a users can direct questions and bug reports. To keep the quality of the Ports Collection as high as possible, we do not accept new ports that are assigned to "ports@FreeBSD.org".] MAINTAINER= asami@FreeBSD.org COMMENT= DVI Previewer for the X Window System [license -- should not be empty] LICENSE= BSD2CLAUSE LICENSE_FILE= ${WRKSRC}/LICENSE [dependencies -- can be empty] RUN_DEPENDS= gs:print/ghostscript [If it requires GNU make, not /usr/bin/make, to build...] USES= gmake [If it is an X application and requires "xmkmf -a" to be run...] USES= imake [this section is for other standard bsd.port.mk variables that do not] belong to any of the above] [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If it requires a "configure" script generated by GNU autoconf to be run] GNU_CONFIGURE= yes [et cetera.] [If it requires options, this section is for options] OPTIONS_DEFINE= DOCS EXAMPLES FOO OPTIONS_DEFAULT= FOO [If options will change the files in plist] OPTIONS_SUB=yes FOO_DESC= Enable foo support FOO_CONFIGURE_ENABLE= foo [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include .... diff --git a/documentation/content/pt-br/books/porters-handbook/porting-why/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/porting-why/_index.adoc similarity index 100% rename from documentation/content/pt-br/books/porters-handbook/porting-why/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/porting-why/_index.adoc diff --git a/documentation/content/pt-br/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/quick-porting/_index.adoc similarity index 94% rename from documentation/content/pt-br/books/porters-handbook/quick-porting/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/quick-porting/_index.adoc index 905a356219..31223a5e39 100644 --- a/documentation/content/pt-br/books/porters-handbook/quick-porting/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/quick-porting/_index.adoc @@ -1,304 +1,302 @@ --- title: Capítulo 3. Port Rápido prev: books/porters-handbook/new-port next: books/porters-handbook/slow-porting --- [[quick-porting]] = Port Rápido :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] -Esta seção descreve como criar rapidamente um novo port. Para aplicativos em que esse método rápido não for adequado, o processo "Slow Porting" está descrito no <>. +Esta seção descreve como criar rapidamente um novo port. Para aplicativos em que esse método rápido não for adequado, o processo "Slow Porting" está descrito no crossref:slow-porting[slow-porting,Port Lento]. Primeiro, obtenha o tarball original e coloque-o em `DISTDIR`, que por padrão é o diretório [.filename]#/usr/ports/distfiles#. [NOTE] ==== -Estas etapas assumem que o software foi compilado de forma simples (out-of-the-box). Em outras palavras, não foi necessária absolutamente nenhuma mudança para o aplicativo funcionar em um sistema FreeBSD. Se alguma coisa teve que ser alterada, por favor consulte o <>. +Estas etapas assumem que o software foi compilado de forma simples (out-of-the-box). Em outras palavras, não foi necessária absolutamente nenhuma mudança para o aplicativo funcionar em um sistema FreeBSD. Se alguma coisa teve que ser alterada, por favor consulte o crossref:slow-porting[slow-porting,Port Lento]. ==== [NOTE] ==== Recomenda-se definir a variável `DEVELOPER` do man:make[1] em [.filename]#/etc/make.conf# antes de começar o trabalho com os ports. [source,shell] .... # echo DEVELOPER=yes >> /etc/make.conf .... Esta configuração habilita o "modo de desenvolvedor" que exibe avisos sobre a descontinuidade de comandos e ativa algumas verificações de qualidade adicionais nas execuções do comando `make`. ==== [[porting-makefile]] == Escrevendo o [.filename]#Makefile# O [.filename]#Makefile# mínimo seria algo assim: [.programlisting] .... # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ PORTNAME= oneko DISTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= youremail@example.com COMMENT= Cat chasing a mouse all over the screen .include .... [NOTE] ==== Em alguns casos, o [.filename]#Makefile# de um port existente pode conter linhas adicionais no cabeçalho, como o nome do port e a data em que foi criado. Esta informação adicional foi declarada obsoleta e está sendo eliminada. ==== Tente entender o exemplo. Não se preocupe com o conteúdo da linha `$FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $`, ela será preenchida automaticamente pelo Subversion quando o port for importado para nossa árvore de ports principais. Um exemplo mais detalhado é mostrado na seção <>. [[porting-desc]] == Escrevendo os Arquivos de Descrição Existem dois arquivos de descrição que são necessários para qualquer port, independente deles estarem empacotados ou não. Eles são o [.filename]#pkg-descr# e o [.filename]#pkg-plist#. Seus prefixos [.filename]#pkg-# distingue-os de outros arquivos. [[porting-pkg-descr]] === [.filename]#pkg-descr# Esta é uma descrição mais longa do port. Um ou alguns parágrafos que explicam o que o port faz é suficiente. [NOTE] ==== Isto _não é_ um manual ou uma descrição detalhada sobre como usar ou compilar o port! _Por favor, tenha cuidado ao copiar do [.filename]#README# ou manpage_. Muitas vezes, eles não são uma descrição concisa do port ou estão em um formato estranho. Por exemplo, as páginas de manual têm espaçamento justificado, o que parece particularmente ruim com fontes monoespaçadas. Por outro lado, o conteúdo de [.filename]#pkg-descr# deve ser mais longo que a linha <> do Makefile. Ele deve explicar com mais profundidade o que é o port. ==== Um [.filename]#pkg-descr# bem escrito descreve o port completamente o suficiente para que os usuários não precisem consultar a documentação ou visitar o site para entender o que o software faz, como ele pode ser útil ou quais recursos particularmente legais ​​ele possui. A menção de certos requisitos, como um kit de ferramentas gráfico, dependências pesadas, ambiente de runtime ou linguagens de implementação, ajuda os usuários a decidir se este port funcionará para eles. Inclua uma URL para a página Web oficial. Prefixe _um_ dos sites (escolha o mais comum) com `WWW:` (seguido por um único espaço) para que as ferramentas automatizadas funcionem corretamente. Se a URI é a raiz do site ou diretório, ele deve ser terminado com uma barra. [NOTE] ==== Se a página web listada para um port não estiver disponível, tente pesquisar na Internet primeiro para ver se o site oficial foi movido, foi renomeado ou se está hospedado em outro lugar. ==== Este exemplo mostra como parece o [.filename]#pkg-descr#: [.programlisting] .... This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ .... [[porting-pkg-plist]] === [.filename]#pkg-plist# Este arquivo lista todos os arquivos instalados pelo port. Ele também é chamado de "packing list" (lista de empacotamento) porque o pacote é gerado empacotando os arquivos listados aqui. Os pathnames são relativos ao prefixo de instalação (geralmente [.filename]#/usr/local#). Aqui está um pequeno exemplo: [.programlisting] .... bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm .... Consulte a manpage do man:pkg-create[8] para detalhes sobre a lista de empacotamento. [NOTE] ==== É recomendado manter todos os nomes de arquivos neste arquivo classificados em ordem alfabética. Isso tornará muito mais fácil verificar as alterações ao atualizar o port. ==== [TIP] ==== Criar uma lista de packing manualmente pode ser uma tarefa muito tediosa. Se o port instalar um grande número de arquivos, <> pode economizar tempo. ==== Há apenas um caso em que o [.filename]#pkg-plist# pode ser omitido de um port. Se o port instalar apenas alguns arquivos, liste-os em `PLIST_FILES`, dentro do [.filename]#Makefile# do port. Por exemplo, poderíamos passar sem o [.filename]#pkg-plist# no port [.filename]#oneko# acima, adicionando estas linhas para no [.filename]#Makefile#: [.programlisting] .... PLIST_FILES= bin/oneko \ man/man1/oneko.1.gz \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm .... [NOTE] ==== Uso de `PLIST_FILES` não deve ser abusado. Ao procurar pela origem de um arquivo, as pessoas geralmente tentam usar o grep através do [.filename]#pkg-plist# nos arquivos na árvore de ports. Listar os arquivos na variável `PLIST_FILES` dentro do [.filename]#Makefile# torna esta busca mais difícil. ==== [TIP] ==== - -Se um port precisar criar um diretório vazio, ou criar diretórios fora do [.filename]#${PREFIX}# durante a instalação, consulte <> para maiores informações. +Se um port precisar criar um diretório vazio, ou criar diretórios fora do [.filename]#${PREFIX}# durante a instalação, consulte crossref:plist[plist-dir-cleaning,Limpando Diretórios Vazios] para maiores informações. ==== [TIP] ==== - -Como `PLIST_FILES` é uma variavel do man:make[1], qualquer entrada com espaços deve ser envolvida por aspas. Por exemplo, se estiver usando palavras-chave descritas em man:pkg-create[8] e na <>, a entrada deve ser citada. +Como `PLIST_FILES` é uma variavel do man:make[1], qualquer entrada com espaços deve ser envolvida por aspas. Por exemplo, se estiver usando palavras-chave descritas em man:pkg-create[8] e na crossref:plist[plist-keywords,Expandindo a Lista de Pacotes com Keywords], a entrada deve ser citada. [.programlisting] .... PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample" .... ==== Mais tarde vamos ver como o [.filename]#pkg-plist# e a `PLIST_FILES` podem ser utilizados para executar <>. [[porting-checksum]] == Criando o Arquivo Checksum Apenas digite `make makesum`. O framework do ports irá gerar automaticamente o [.filename]#distinfo#. Não tente gerar o arquivo manualmente. [[porting-testing]] == Testando o Port Certifique-se de que as regras do port façam exatamente o que é desejado, incluindo o empacotamento do port. Estes são os pontos importantes a serem verificados: * [.filename]#pkg-plist# não contém nada não instalado pelo port. * [.filename]#pkg-plist# contém tudo o que é instalado pelo port. * O port pode ser instalado usando o target `install`. Isso verifica se o script de instalação está funcionando corretamente. * O port pode ser desinstalado adequadamente usando o target `deinstall`. Isso verifica se o script de desinstalação funciona corretamente. * O port só tem acesso aos recursos de rede durante a fase target `fetch`. Isto é importante para os construtores de pacotes, tais como o package:ports-mgmt/poudriere[]. -* Certifique-se de que o comando `make package` pode ser executado como um usuário normal (ou seja, não como `root`). Se isso falhar, talvez seja necessário corrigir o software. Veja a <> e também a <>. +* Certifique-se de que o comando `make package` pode ser executado como um usuário normal (ou seja, não como `root`). Se isso falhar, talvez seja necessário corrigir o software. Veja a crossref:uses[uses-fakeroot,`fakeroot`] e também a crossref:uses[uses-uidfix,`uidfix`]. [.procedure] ==== *Procedure: Ordem Recomendada de Teste* . `make stage` . `make stage-qa` . `make package` . `make install` . `make deinstall` . `make package` (como usuário) ==== Certifique-se de que nenhum aviso é exibido em nenhum dos estágios. -Testes automatizados completos podem ser feitos com o package:ports-mgmt/poudriere[] da coleção do Ports, veja a <> para maiores informações. Ele mantém `jails` onde todas as etapas mostradas acima podem ser testadas sem afetar o estado do sistema host. +Testes automatizados completos podem ser feitos com o package:ports-mgmt/poudriere[] da coleção do Ports, veja a crossref:testing[testing-poudriere,Poudriere] para maiores informações. Ele mantém `jails` onde todas as etapas mostradas acima podem ser testadas sem afetar o estado do sistema host. [[porting-portlint]] == Verificando o Port com `portlint` Por favor, use o `portlint` para ver se o port está de acordo com as nossas diretrizes. O programa package:ports-mgmt/portlint[] faz parte da coleção de ports. Em particular, ele verifica se o <> está correto e se o <> está nomeado apropriadamente. [IMPORTANT] ==== Não siga cegamente a saída do `portlint`. Ela é uma ferramenta de lint estática e às vezes comete erros. ==== [[porting-submitting]] == Enviando o Novo Port Antes de enviar o novo port, leia <>. Uma vez feliz com o port, a única coisa que resta é colocá-lo na árvore principal do FreeBSD e deixar todo mundo feliz também. [IMPORTANT] ==== Nós não precisamos do diretório [.filename]#work# ou do pacote [.filename]#pkgname.tgz#, então exclua-os agora. ==== Em seguida, crie um man:patch[1]. Assumindo que o port é chamado `oneko` e está na categoria `games`. [[porting-submitting-diff]] .Criando um [.filename]#.diff# para um Novo Port [example] ==== Adicione todos os arquivos com `svn add`. Utilize o `cd` e vá para a base da árvore de ports, para que os caminhos completos dos arquivos alterados sejam incluídos no diff, então gere o diff com `svn diff`. Por exemplo: [source,shell] .... % svn add . % cd ../.. % svn diff games/oneko > oneko.diff .... [IMPORTANT] ====== Para ser mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de ports, por favor, gere o [.filename]#.diff# da base da sua árvore de ports. ====== ==== Envie o [.filename]#oneko.diff# com o https://bugs.freebsd.org/submit/[formulário de submissão de bugs]. Use product "Ports & Packages", component "Individual Port(s)" e siga as diretrizes mostradas lá. Adicione uma breve descrição do programa ao campo Description do PR (talvez uma versão curta do `COMMENT`), e lembre-se de adicionar o [.filename]#oneko.diff# como um anexo. [NOTE] ==== Dar uma boa descrição no resumo do relatório de problema facilita muito o trabalho dos commiters de ports. Preferimos algo como "New port: `__category/portname breve descrição do port__`" para novos ports. Usar este esquema torna mais fácil e rápido começar o trabalho para fazer o commit de um novo port. ==== Depois de enviar o port, por favor, seja paciente. O tempo necessário para incluir um novo port no FreeBSD pode variar de alguns dias até alguns meses. Um formulário simples de pesquisa no banco de dados do Relatório de Problemas está disponível em https://bugs.freebsd.org/bugzilla/query.cgi[]. Para obter uma listagem dos PRs _abertos_ para os ports, selecione _Open_ e _Ports & Packages_ no formulário de pesquisa, clique em btn:[Search]. Depois de analisar o novo port, nós responderemos se necessário, e iremos adicioná-lo a árvore. O nome do remetente também será adicionado à lista de extref:{contributors}[Contribuidores Adicionais do FreeBSD, contrib-additional] e outros arquivos. Também é possível enviar ports usando um arquivo man:shar[1]. Usando o exemplo anterior com o port `oneko` acima. [[porting-submitting-shar]] .Criando um [.filename]#.shar# para um Novo Port [example] ==== vá para o diretório acima, onde o diretório do port está localizado, e use `tar` para criar o arquivo shar: [source,shell] .... % cd .. % tar cf oneko.shar --format shar oneko .... ==== [.filename]#oneko.shar# pode ser enviado da mesma maneira que [.filename]#oneko.diff# acima. diff --git a/documentation/content/pt-br/books/porters-handbook/security/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/security/_index.adoc similarity index 100% rename from documentation/content/pt-br/books/porters-handbook/security/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/security/_index.adoc diff --git a/documentation/content/pt-br/books/porters-handbook/slow-porting/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/slow-porting/_index.adoc similarity index 96% rename from documentation/content/pt-br/books/porters-handbook/slow-porting/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/slow-porting/_index.adoc index b1d466a219..c58c9bcd1e 100644 --- a/documentation/content/pt-br/books/porters-handbook/slow-porting/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/slow-porting/_index.adoc @@ -1,298 +1,297 @@ --- title: Capítulo 4. Port Lento prev: books/porters-handbook/quick-porting next: books/porters-handbook/makefiles --- [[slow-porting]] = Port Lento :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 4 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Certo, então não foi tão simples e o port precisou de algumas modificações para poder funcionar. Nesta seção, vamos explicar passo a passo como modificá-lo para que funcione com o paradigma do ports. [[slow-work]] == Como as Coisas Funcionam Primeiro, esta é a sequência de eventos que ocorre quando o usuário executa `make` no diretório do port. Ter o [.filename]#bsd.port.mk# aberto em outra janela enquanto lê esta seção realmente irá ajudar a entender melhor. Mas não se preocupe, não são muitas as pessoas que entendem exatamente como o [.filename]#bsd.port.mk# funciona..._:-)_ [.procedure] ==== . O target `fetch` é executado. O target `fetch` é responsável por garantir que o tarball exista localmente em `DISTDIR`. Se o `fetch` não puder encontrar os arquivos necessários no `DISTDIR` ele procurará a URL na variável `MASTER_SITES`, definida no Makefile, assim como nos nossos mirrors FTP nos quais colocamos os distfiles como backup. Em seguida, ele tentará buscar o arquivo de distribuição nomeado com `FETCH`, assumindo que o site solicitante tem acesso direto à Internet. Se isso for bem sucedido, ele salvará o arquivo em `DISTDIR` para uso futuro e continuará. . O target `extract` é executado. Ele procura pelo arquivo de distribuição do port (normalmente um tarball compactado) em `DISTDIR` e irá descompactá-lo em um subdiretório temporário especificado por `WRKDIR` (padrão é [.filename]#work#). . O target `patch` é executado. Primeiro, quaisquer patches definidos em `PATCHFILES` são aplicados. Segundo, se arquivos de patch nomeados [.filename]#patch-*# forem encontrados em `PATCHDIR` (padrão para o subdiretório [.filename]#files#), eles serão aplicados neste momento em ordem alfabética. . O target `configure` é executado. Ele pode fazer qualquer uma de muitas coisas diferentes. .. Se existir, [.filename]#scripts/configure# é executado. .. E se `HAS_CONFIGURE` ou `GNU_CONFIGURE` está definido, [.filename]#WRKSRC/configure# é executado. . O target `build` é executado. Ele é responsável por mudar para o diretório de trabalho privado do port (`WRKSRC`) e compila-lo. -. O target `stage` é executado. Este coloca o conjunto final de arquivos construídos em um diretório temporário (`STAGEDIR`, Veja <>). A hierarquia deste diretório espelha a do sistema no qual o pacote será instalado. +. O target `stage` é executado. Este coloca o conjunto final de arquivos construídos em um diretório temporário (`STAGEDIR`, Veja crossref:special[staging,Staging]). A hierarquia deste diretório espelha a do sistema no qual o pacote será instalado. . O target `package` é executado. Ele cria um pacote usando os arquivos do diretório temporário criado durante o target `stage` e o [.filename]#pkg-plist# do port. . O target `install` é executado. Este instala o pacote criado durante o target `package` no host. ==== As ações acima são padrão. Além disso, defina os targets `pre-_something_` ou `post-_something_`, ou insira scripts com esses nomes no subdiretório [.filename]#scripts#, e eles serão executados antes ou depois das ações padrão serem executadas. Por exemplo, se houver um target `post-extract` definido no [.filename]#Makefile# e um arquivo [.filename]#pre-build# no subdiretório [.filename]#scripts#, o target `post-extract` será chamado após as ações de extração regulares e [.filename]#pre-build# será executado antes que as regras de compilação padrão sejam feitas. Recomenda-se usar targets no [.filename]#Makefile# se as ações forem simples, porque será mais fácil para alguém descobrir que tipo de ação não padrão o port necessita. As ações padrão são feitas pelos targets `do-_something_` do [.filename]#bsd.port.mk#. Por exemplo, os comandos para extrair um port estão no target `do-extract`. Se o target padrão não fizer o trabalho direito, redefina o target `do-_something_` no [.filename]#Makefile#. [NOTE] ==== O target "principal" (por exemplo, `extract`, `configure`, etc.) fazem nada mais do que certificar-se de que todos os estágios até aquele estão concluídos e chamar os targets ou scripts reais, e eles não pretendem ser alterados. Para consertar a extração, corrija `do-extract`, mas nunca mude a forma como `extract` opera! Além disso, o target `post-deinstall` é inválido e não é executado pela infraestrutura de ports. ==== Agora que o que acontece quando o usuário digita `make install` é melhor entendido, vamos seguir as etapas recomendadas para criar o port perfeito. [[slow-sources]] == Obtendo os Fontes Originais Obtenha os fontes originais (normalmente) como um tarball compactado ([.filename]#foo.tar.gz# ou [.filename]#foo.tar.bz2#) e copie-o para `DISTDIR`. Use fontes do _mainstream_ sempre que possível. -Definir a variável `MASTER_SITES` para refletir onde o tarball original reside. Existem definições abreviadas para a maioria dos sites mainstream em [.filename]#bsd.sites.mk#. Por favor, use esses sites - e as definições associadas--se for possível, para ajudar a evitar o problema de ter as mesmas informações repetidas várias vezes na base de origem. Como esses sites tendem a mudar com o tempo, isso se torna um pesadelo de manutenção para todos os envolvidos. Veja <> para detalhes. +Definir a variável `MASTER_SITES` para refletir onde o tarball original reside. Existem definições abreviadas para a maioria dos sites mainstream em [.filename]#bsd.sites.mk#. Por favor, use esses sites - e as definições associadas--se for possível, para ajudar a evitar o problema de ter as mesmas informações repetidas várias vezes na base de origem. Como esses sites tendem a mudar com o tempo, isso se torna um pesadelo de manutenção para todos os envolvidos. Veja crossref:makefiles[makefile-master_sites,`MASTER_SITES`] para detalhes. Se não houver nenhum site FTP/HTTP bem conectado à rede ou se puder encontrar apenas sites com formatos irritantemente não-padrão, coloque uma cópia em um servidor FTP ou HTTP confiável (por exemplo, uma home page). Se um lugar conveniente e confiável para colocar o distfile não puder ser encontrado, nós podemos "hospedar" em `ftp.FreeBSD.org`; no entanto, esta é a solução menos preferida. O distfile deve ser colocado em [.filename]#~/public_distfiles/# da conta `freefall` de alguém. Peça para a pessoa que for fazer o commit do port para realizer isso. Essa pessoa também irá definir `MASTER_SITES` para `LOCAL/_username_` onde `_username_` é o seu login do cluster do FreeBSD. Se o distfile do port mudar o tempo todo sem nenhum tipo de atualização de versão pelo autor, considere colocar o distfile em uma página pessoal e liste-a como o `MASTER_SITES` primário. Tente falar com o autor do port para parar de fazer isso; Isso realmente ajuda a estabelecer algum tipo de controle de código-fonte. Hospedar uma versão específica impedirá que os usuários obtenham erros de `checksum mismatch`, e também irá reduzir a carga de trabalho dos mantenedores do nosso site FTP. Além disso, se houver apenas um site master para o port, recomenda-se armazenar um backup em uma home page e listá-lo como o `MASTER_SITES` secundário. Se o port exigir patches adicionais disponíveis na Internet, baixe-os também e coloque-os em `DISTDIR`. Não se preocupe se eles vierem de um site diferente de onde vem o tarball do código fonte principal, temos uma maneira de lidar com essas situações (veja a descrição <> abaixo). [[slow-modifying]] == Modificando o Port Desempacote uma cópia do tarball em um diretório privado e faça as alterações necessárias para que o port compile corretamente sob a versão atual do FreeBSD. _Atenção dobrada_ nessas etapas, pois elas serão necessárias para automatizar o processo em breve. Tudo, incluindo a exclusão, adição ou modificação de arquivos, devem ser realizados usando um script automatizado ou um arquivo patch quando o port estiver finalizado. Se o port exigir interação/customização significativa do usuário para compilar ou instalar, dê uma olhada em um dos scripts Configure clássicos de Larry Wall e talvez faça algo semelhante. O objetivo da nova coleção de ports é fazer com que cada port seja "plug-and-play" o quanto possível para o usuário final, usando um mínimo de espaço em disco. [NOTE] ==== A menos que explicitamente declarado, os arquivos de patch, scripts e outros arquivos criados e contribuídos para a coleção de ports do FreeBSD são assumidos como cobertos pelas condições de copyright padrão do BSD. ==== [[slow-patch]] == Patching Na preparação do port, arquivos que forem adicionados ou alterados podem ser gravados com man:diff[1] para posterior inclusão em um man:patch[1]. Fazer isso com um arquivo típico envolve salvar uma cópia do arquivo original antes de fazer qualquer alteração usando um sufixo [.filename]#.orig#. [source,shell] .... % cp file file.orig .... Depois que todas as alterações forem realizadas, `cd` de volta ao diretório do port. Execute `make makepatch` para gerar arquivos de patch atualizados no diretório [.filename]#files#. [TIP] ==== - -Usar `BINARY_ALIAS` para substituir comandos codificados durante a compilação e para evitar patching de arquivos de compilação. Veja <> para maiores informações. +Usar `BINARY_ALIAS` para substituir comandos codificados durante a compilação e para evitar patching de arquivos de compilação. Veja crossref:makefiles[binary-alias,Use `BINARY_ALIAS` para Renomear Comandos Em Vez de Aplicar Patch na Compilação] para maiores informações. ==== [[slow-patch-rules]] === Regras Gerais para Patching Arquivos patch são armazenados em `PATCHDIR`, geralmente [.filename]#files/#, de onde serão aplicados automaticamente. Todas os patches devem ser relativos ao `WRKSRC`. Tipicamente `WRKSRC` é um subdiretório de `WRKDIR`, o diretório onde o distfile é extraído. Execute `make -V WRKSRC` para ver o caminho real. Os nomes dos patches devem seguir estas regras: * Evite ter mais de um patch modificando o mesmo arquivo. Por exemplo, ter os dois [.filename]#patch-foobar.c# e [.filename]#patch-foobar.c2# fazendo alterações em [.filename]#${WRKSRC}/foobar.c# torna-os frágeis e difíceis de serem depurados. * Ao criar nomes para arquivos de patch, substitua cada underline (`_`) com dois underlines (`__`) e cada barra (`/`) com um underline (`_`). Por exemplo, para corrigir um arquivo chamado [.filename]#src/freeglut_joystick.c# nomeie o patch correspondente [.filename]#patch-src_freeglut__joystick.c#. Não nomeie patches como [.filename]#patch-aa# ou [.filename]#patch-ab#. Sempre use o caminho e o nome do arquivo nos nomes dos patches. O `make makepatch` gera automaticamente os nomes corretos. * Um patch pode modificar vários arquivos se as alterações estiverem relacionadas e o patch tiver o nome apropriado. Por exemplo, [.filename]#patch-add-missing-stdlib.h#. * Use apenas caracteres `[-+._ a-zA-Z0-9]` para nomear patches. Em particular, não use ``::`` como um separador de path, use `_` no lugar. Minimize a quantidade de mudanças de espaço em branco não funcionais em patches. É comum no mundo Open Source para projetos compartilhar grandes quantidades de uma base de código, mas obedecer a regras de recuo e estilo diferentes. Ao usar uma funcionalidade funcional de um projeto para consertar áreas similares em outra, por favor, tenha cuidado: o patch resultante pode estar cheio de mudanças não-funcionais. Ele não só aumenta o tamanho do repositório do ports, mas torna difícil descobrir o que exatamente causou o problema e o que foi alterado em todos. Se um arquivo precisar ser excluído, faça-o no target `post-extract` em vez de como parte do patch. [[slow-patch-manual]] === Geração Manual de Patches [NOTE] ==== A criação manual de patches geralmente não é necessária. A geração automática de patches, conforme descrito anteriormente nesta seção, é o método preferido. No entanto, patches manuais podem ser necessários ocasionalmente. ==== Patches são salvos em arquivos nomeados como [.filename]#patch-*# onde _*_ indica o nome do caminho do arquivo que está sendo feito o patch, como [.filename]#patch-imakefile# ou [.filename]#patch-src-config.h#. Depois que o arquivo foi modificado, man:diff[1] é usado para registrar as diferenças entre a versão original e a modificada. `-u` faz com que o man:diff[1] produza diffs "unificados", a forma preferida. [source,shell] .... % diff -u file.orig file > patch-pathname-file .... Ao gerar patches para novos arquivos adicionados, `-N` é usado para dizer ao man:diff[1] para tratar o arquivo original inexistente como se existisse, mas estava vazio: [source,shell] .... % diff -u -N newfile.orig newfile > patch-pathname-newfile .... Não adicione Strings RCS `$FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $` em patches. Quando os patches são adicionados ao repositório Subversion com `svn add`, a propriedade `fbsd:nokeywords` é definida para `yes` automaticamente para que as keywords no patch não sejam modificadas no commit. A propriedade pode ser adicionada manualmente `svn propset fbsd:nokeywords yes _files..._`. Usar a opção (`-r`) do man:diff[1] para gerar patches é razoável, mas por favor, analise os patches resultantes para se certificar de que não há nenhum lixo desnecessário neles. Em particular, diffs entre dois arquivos de backup, quando o port usa `Imake` ou GNU `configure`, etc., diffs de [.filename]##Makefile##s são desnecessários e devem ser eliminados. Se for necessário editar o [.filename]#configure.in# e executar o `autoconf` para regerar o `configure`, não gere diffs do `configure` (ele geralmente cresce para algumas milhares de linhas!). Em vez disso, defina `USES=autoreconf` e gere os diffs no [.filename]#configure.in#. [[slow-patch-automatic-replacements]] === Substituições Automáticas Simples Substituições simples podem ser realizadas diretamente do [.filename]#Makefile# do port usando o modo in-loco do man:sed[1]. Isso é útil quando as alterações usam o valor de uma variável: [.programlisting] .... post-patch: @${REINPLACE_CMD} -e 's|/usr/local|${PREFIX}|g' ${WRKSRC}/Makefile .... [IMPORTANT] ==== Use o man:sed[1] apenas para substituir conteúdo de variáveis. Você deve usar arquivos patch em vez do man:sed[1] para substituir conteúdo estático. ==== Muitas vezes, o software sendo portado usa a convenção CR/LF nos arquivos fonte. Isso pode causar problemas com correções adicionais, avisos do compilador ou execução de scripts (como `/bin/sh^M não encontrado`.) Para converter rapidamente todos os arquivos de CR/LF para apenas LF, adicione essa entrada ao [.filename]#Makefile# do port: [.programlisting] .... USES= dos2unix .... Uma lista de arquivos específicos para conversão pode ser informada: [.programlisting] .... USES= dos2unix DOS2UNIX_FILES= util.c util.h .... Use `DOS2UNIX_REGEX` para converter um grupo de arquivos em subdiretórios. Seu argumento é um man:find[1] compatível com expressão regular. Mais sobre o formato está em man:re_format[7]. Esta opção é útil para converter todos os arquivos de uma determinada extensão. Por exemplo, converta todos os arquivos de código-fonte, deixando os arquivos binários intactos: [.programlisting] .... USES= dos2unix DOS2UNIX_REGEX= .*\.([ch]|cpp) .... Uma opção similar é `DOS2UNIX_GLOB`, que executa o `find` para cada elemento listado nele. [.programlisting] .... USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h .... O diretório base para a conversão pode ser definido. Isso é útil quando há vários distfiles e vários arquivos contidos que requerem conversão de fim de linha. [.programlisting] .... USES= dos2unix DOS2UNIX_WRKSRC= ${WRKDIR} .... [[slow-patch-extra]] === Corrigindo Condicionalmente Alguns ports precisam de patches que são aplicados apenas para versões específicas do FreeBSD ou quando uma determinada opção é ativada ou desativada. Os patches condicionais são especificados colocando-se os caminhos completos para os arquivos de patch em `EXTRA_PATCHES`. [[slow-patch-extra-ex1]] .Aplicando um Patch para uma Versão Específica do FreeBSD [example] ==== [.programlisting] .... .include # Patch in the iconv const qualifier before this .if ${OPSYS} == FreeBSD && ${OSVERSION} < 1100069 EXTRA_PATCHES= ${PATCHDIR}/extra-patch-fbsd10 .endif .include .... ==== [[slow-patch-extra-ex2]] .Aplicando Opcionalmente um Patch [example] ==== -Quando um <> requer um patch, use `OPT_EXTRA_PATCHES` e `OPT_EXTRA_PATCHES_OFF` para fazer o patch condicional na opção `_opt_`. Veja <> Para maiores informações. +Quando um crossref:makefiles[makefile-options,option] requer um patch, use `OPT_EXTRA_PATCHES` e `OPT_EXTRA_PATCHES_OFF` para fazer o patch condicional na opção `_opt_`. Veja <> Para maiores informações. [.programlisting] .... OPTIONS_DEFINE= FOO BAR FOO_EXTRA_PATCHES= ${PATCHDIR}/extra-patch-foo BAR_EXTRA_PATCHES_OFF= ${PATCHDIR}/extra-patch-bar.c \ ${PATCHDIR}/extra-patch-bar.h .... ==== [[slow-patch-extra-ex-dirs]] .Usando `EXTRA_PATCHES` Com um Diretório [example] ==== As vezes, existem muitos patches que são necessários para um recurso, neste caso, é possível apontar `EXTRA_PATCHES` para um diretório, e ele aplicará automaticamente todos os arquivos nomeados como [.filename]#patch*# nele. Crie um subdiretório em [.filename]#${PATCHDIR}#, e mova os patches para ele. Por exemplo: [source,shell] .... % ls -l files/foo-patches -rw-r--r-- 1 root wheel 350 Jan 16 01:27 patch-Makefile.in -rw-r--r-- 1 root wheel 3084 Jan 18 15:37 patch-configure .... Então adicione isso ao [.filename]#Makefile#: [.programlisting] .... OPTIONS_DEFINE= FOO FOO_EXTRA_PATCHES= ${PATCHDIR}/foo-patches .... O framework irá então usar todos os arquivos nomeados [.filename]#patch*# nesse diretório. ==== [[slow-configure]] == Configurando Inclua quaisquer comandos de personalização adicionais no script [.filename]#configure# e salve-o no subdiretório [.filename]#scripts#. Como mencionado acima, também é possível fazer isso com targets no [.filename]#Makefile# e/ou scripts com o nome [.filename]#pre-configure# ou [.filename]#post-configure#. [[slow-user-input]] == Manipulando a Entrada do Usuário Se o port requer intervenção do usuário para build, configure ou install, defina `IS_INTERACTIVE` no [.filename]#Makefile#. Isso fará com que os "overnight builds" pulem ele. Se o usuário definir a variável `BATCH` em seu ambiente (e se o usuário definir a variável `INTERATIVE`, então _apenas_ aqueles ports que requerem interação serão compilados). Isso economizará muito tempo perdido no conjunto de máquinas que continuamente compilam ports (veja abaixo). Também é recomendado que, se houver respostas padrão razoáveis ​​para as perguntas, `PACKAGE_BUILDING` pode usado para desativar a intervenção do usuário quando o mesmo estiver definido. Isso nos permitirá compilar os pacotes para CDROMs e FTP. diff --git a/documentation/content/pt-br/books/porters-handbook/special/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/special/_index.adoc similarity index 97% rename from documentation/content/pt-br/books/porters-handbook/special/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/special/_index.adoc index 8750eba096..a79e3f7b5c 100644 --- a/documentation/content/pt-br/books/porters-handbook/special/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/special/_index.adoc @@ -1,4313 +1,4313 @@ --- title: Capítulo 6. Considerações Especiais prev: books/porters-handbook/makefiles next: books/porters-handbook/flavors --- [[special]] = Considerações Especiais :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Esta seção explica as coisas mais comuns a se considerar ao criar um port. [[staging]] == Staging -[.filename]#bsd.port.mk# espera que os ports trabalhem com um "stage directory". Isso significa que um port não deve instalar arquivos diretamente nos diretórios de destino regulares (isto é, sob o `PREFIX`, por exemplo), mas em um diretório separado a partir do qual o pacote será construído. Em muitos casos, isso não requer privilégios de root, tornando possível criar pacotes como um usuário não privilegiado. Com o staging, o port é compilado e instalado no diretório sde estágio, `STAGEDIR`. Um pacote é criado a partir do diretório de estágio e, em seguida, instalado no sistema. As ferramentas Automake referem-se a este conceito como `DESTDIR`, mas no FreeBSD, `DESTDIR` tem um significado diferente (veja <>). +[.filename]#bsd.port.mk# espera que os ports trabalhem com um "stage directory". Isso significa que um port não deve instalar arquivos diretamente nos diretórios de destino regulares (isto é, sob o `PREFIX`, por exemplo), mas em um diretório separado a partir do qual o pacote será construído. Em muitos casos, isso não requer privilégios de root, tornando possível criar pacotes como um usuário não privilegiado. Com o staging, o port é compilado e instalado no diretório sde estágio, `STAGEDIR`. Um pacote é criado a partir do diretório de estágio e, em seguida, instalado no sistema. As ferramentas Automake referem-se a este conceito como `DESTDIR`, mas no FreeBSD, `DESTDIR` tem um significado diferente (veja crossref:testing[porting-prefix,`PREFIX` e `DESTDIR`]). [NOTE] ==== -Nenhum port _realmente_ precisa de root. Ele pode ser evitado principalmente usando <>. Se o port ainda executa comandos como man:chown[8], man:chgrp[1] ou força o proprietário ou grupo com man:install[1] então use <> para enganar essas chamadas. Algumas modificações no [.filename]#Makefile# do port serão necessárias. +Nenhum port _realmente_ precisa de root. Ele pode ser evitado principalmente usando crossref:uses[uses-uidfix,`USES=uidfix`]. Se o port ainda executa comandos como man:chown[8], man:chgrp[1] ou força o proprietário ou grupo com man:install[1] então use crossref:uses[uses-fakeroot,`USES=fakeroot`] para enganar essas chamadas. Algumas modificações no [.filename]#Makefile# do port serão necessárias. ==== Os meta ports, ou ports que não instalam arquivos por si mesmos e apenas dependem de outros ports, devem evitar extrair desnecessariamente man:mtree[8] para o diretório de estágio. Este é o layout básico do diretório do pacote, e estes diretórios vazios serão vistos como órfãos. Para prevenir extração do man:mtree[8], adicione esta linha: [.programlisting] .... NO_MTREE= yes .... [TIP] ==== Metaports devem usar <>. Ele configura padrões para ports que não baixam, criam ou instalam nada. ==== Staging é ativado pré-fixando a variável `STAGEDIR` para caminhos usados ​​nos targets `pre-install`, `do-install` e `post-install` (veja os exemplos no livro). Normalmente, isso inclui as variáveis `PREFIX`, `ETCDIR`, `DATADIR`, `EXEMPLESDIR`, `MANPREFIX`, `DOCSDIR`, e assim por diante. Os diretórios devem ser criados como parte do target `post-install`. Evite usar caminhos absolutos sempre que possível. [TIP] ==== Ports que instalam módulos do kernel devem preceder a variável `STAGEDIR` em seus destinos, padrão [.filename]#/boot/modules#. ==== [[staging-symlink]] === Lidando com Links Simbólicos Ao criar um link simbólico, os links relativos são fortemente recomendados. Use `${RLN}` para criar links simbólicos relativos. Ele usa o man:install[1] por baixo dos panos para descobrir automaticamente o link relativo a ser criado. [[staging-ex1]] .Crie Links Simbólicos Relativos Automaticamente [example] ==== `${RLN}` usa o recurso simbólico relativo do man:install[1] que libera o mantenedor do port de computar o caminho relativo. [.programlisting] .... ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so ${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar ${RLN} ${STAGEDIR}/var/cache/foo ${STAGEDIR}${PREFIX}/share/foo .... Irá gerar: [source,shell] .... % ls -lF ${STAGEDIR}${PREFIX}/lib lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42 -rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42* % ls -lF ${STAGEDIR}${PREFIX}/bin lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar % ls -lF ${STAGEDIRDIR}${PREFIX}/share lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> ../../../var/cache/foo .... ==== [[bundled-libs]] == Bibliotecas Empacotadas (Bundled) Esta seção explica porque as dependências agrupadas(bundled) são consideradas ruins e o que fazer com elas. [[bundled-libs-why-bad]] === Por Que as Bibliotecas Agrupadas(Bundled) São Ruins Alguns softwares requerem que o mantenedor do port localize bibliotecas de terceiros e adicione as dependências necessárias ao port. Outros softwares agrupam todas as bibliotecas necessárias no arquivo de distribuição. A segunda abordagem parece mais fácil no começo, mas há algumas desvantagens sérias: Esta lista é vagamente baseada nas wikis https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries[Fedora] e http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies[Gentoo], ambas licenciadas sob http://creativecommons.org/licenses/by-sa/3.0/[CC-BY-SA 3.0]. Segurança:: Se vulnerabilidades forem encontradas na biblioteca e arrumadas no upstream, elas podem não ser consertadas na biblioteca empacotada com o port. Uma razão pode ser que o autor não esteja ciente do problema. Isto significa que o mantenedor do port deve consertá-las, ou atualizar para uma versão não vulnerável e enviar um patch para o autor. Isso tudo leva tempo, o que resulta em software vulnerável por mais tempo do que o necessário. Isso, por sua vez, torna mais difícil coordenar uma correção sem vazamento desnecessário de informações sobre a vulnerabilidade. Bugs:: Esse problema é semelhante ao problema de segurança no último parágrafo, mas geralmente menos grave. Forking:: É mais fácil para o autor criar um fork da biblioteca depois que ela é empacotada. Embora seja conveniente à primeira vista, isso significa que o código diverge do upstream, dificultando o tratamento da segurança ou outros problemas com o software. A razão para isso é que o patching se torna mais difícil. + Outro problema de forking é que, como o código diverge do upstream, os bugs são resolvidos repetidamente em vez de apenas uma vez em um local central. Isso, em primeiro lugar, anula a ideia de software de código aberto. Colisão de símbolo:: Quando uma biblioteca é instalada no sistema, ela pode colidir com a versão empacotada. Isso pode causar erros imediatos no tempo de compilação ou link. Também pode causar erros ao executar o programa, o que pode ser mais difícil de rastrear. O último problema poderia ser causado porque as versões das duas bibliotecas são incompatíveis. Licenciamento:: Ao agrupar projetos de diferentes fontes, os problemas de licença podem surgir com mais facilidade, especialmente quando as licenças são incompatíveis. Desperdício de recursos:: Bibliotecas empacotadas desperdiçam recursos em vários níveis. Demora mais para compilar o aplicativo real, especialmente se essas bibliotecas já estiverem presentes no sistema. Em tempo de execução, elas podem ocupar memória desnecessária quando a biblioteca do sistema já está carregada por um programa e a biblioteca agrupada é carregada por outro programa. Desperdício de esforço:: Quando uma biblioteca precisa de patches para o FreeBSD, esses patches precisam ser duplicados novamente na biblioteca. Isso desperdiça tempo do desenvolvedor porque os patches podem não ser aplicados de forma limpa. Também pode ser difícil perceber que estes patches são necessários em primeiro lugar. [[bundled-libs-practices]] === O Que Fazer em Relação às Bibliotecas Agrupadas Sempre que possível, use a versão separada da biblioteca adicionando um `LIB_DEPENDS` para o port. Se esse port ainda não existir, considere criá-lo. Use bibliotecas agrupadas somente se o upstream tiver um bom histórico de segurança e se o uso de versões não agrupadas originarem patches excessivamente complexos. [NOTE] ==== Em alguns casos muito especiais, por exemplo, emuladores, como o Wine, um port tem que agrupar bibliotecas, porque elas estão em uma arquitetura diferente ou foram modificadas para se adequarem ao uso do software. Nesse caso, essas bibliotecas não devem ser expostas a outros ports para vinculação. Adicione `BUNDLE_LIBS=yes` no [.filename]#Makefile# do port. Isso vai dizer ao man:pkg[8] para não computar as bibliotecas fornecidas. Pergunte sempre à equipe de gerenciamento do ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org] antes de adicionar isso a um port. ==== [[porting-shlibs]] == Bibliotecas Compartilhadas Se o port instalar uma ou mais bibliotecas compartilhadas, defina a variável `USE_LDCONFIG` para o make , a qual irá instruir o [.filename]#bsd.port.mk# para executar o `${LDCONFIG} -m` no diretório onde a nova biblioteca está instalada (geralmente em [.filename]#PREFIX/lib#) durante o target `post-install` para registrá-la no cache da biblioteca compartilhada. Esta variável, quando definida, também facilitará a adição do par `@exec /sbin/ldconfig -m` e `@unexec /sbin/ldconfig -R` no [.filename]#pkg-plist#, para que o usuário que instalou o pacote possa começar a usar a biblioteca compartilhada imediatamente e para que a desinstalação não faça com que o sistema acredite que a biblioteca ainda está lá. [.programlisting] .... USE_LDCONFIG= yes .... O diretório padrão pode ser substituído configurando a variável `USE_LDCONFIG` para uma lista de diretórios nos quais as bibliotecas compartilhadas devem ser instaladas. Por exemplo, se o port instalar bibliotecas compartilhadas em [.filename]#PREFIX/lib/foo# e [.filename]#PREFIXO/lib/bar# utilize isso no [.filename]#Makefile#: [.programlisting] .... USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar .... Por favor, verifique novamente, muitas vezes isso não é necessário ou é algo que pode ser evitado através do uso da opção `-rpath` ou da configuração da variável `LD_RUN_PATH` durante a fase de vinculação (consulte package:lang/mosml[] para um exemplo), ou através de um shell-wrapper que defina o `LD_LIBRARY_PATH` antes de executar o binário, como por exemplo o package:www/seamonkey[] faz. Ao instalar bibliotecas de 32 bits em um sistema de 64 bits, use `USE_LDCONFIG32` como alternativa. Se o software usa o <>, e especificamente, o `libtool`, adicione <>. Quando o número da versão da biblioteca principal aumenta na atualização para a nova versão do port, todos os outros ports que se vinculam à biblioteca afetada devem ter seu `PORTREVISION` incrementado, para forçar a recompilação com a nova versão da biblioteca. [[porting-restrictions]] == Ports com Restrições de Distribuição ou Preocupações Legais As licenças variam e algumas delas impõem restrições sobre como o aplicativo pode ser empacotado, se pode ser vendido com fins lucrativos e assim por diante. [IMPORTANT] ==== É de responsabilidade de um mantenedor de um port ler os termos de licenciamento do software e certificar-se de que o projeto do FreeBSD não será responsabilizado por violá-los, redistribuindo o código fonte ou os binários compilados via FTP/HTTP ou CD-ROM. Se estiver em dúvida, entre em contato com a http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[Lista de discussão de ports do FreeBSD]. ==== Em situações como esta, as variáveis ​​descritas nas próximas seções podem ser definidas. [[porting-restrictions-no_package]] === `NO_PACKAGE` Esta variável indica que não podemos gerar um pacote binário da aplicação. Por exemplo, a licença pode proibir a redistribuição binária, ou pode proibir a distribuição de pacotes criados a partir de código adaptado. No entanto, o `DISTFILES` do port pode ser livremente espelhado no FTP/HTTP. Eles também podem ser distribuídos em um CD-ROM (ou mídia similar), a menos que a variável `NO_CDROM` esteja definida também. Se o pacote binário geralmente não é útil, e o aplicativo sempre deve ser compilado a partir do código-fonte, use o `NO_PACKAGE`. Por exemplo, se o aplicativo tiver informações de configuração específicas do site codificadas nele em tempo de compilação, defina o `NO_PACKAGE`. Defina a variável `NO_PACKAGE` para uma string descrevendo o motivo pelo qual o pacote não pode ser gerado. [[porting-restrictions-no_cdrom]] === `NO_CDROM` Esta variável sozinha indica que, embora tenhamos permissão para gerar pacotes binários, não podemos colocar nem esses pacotes nem o `DISTFILES` em um CD-ROM (ou mídia similar) para revenda. No entanto, os pacotes binários e os `DISTFILES` do ports ainda estarão disponíveis via FTP/HTTP. Se esta variável for definida junto com `NO_PACKAGE`, então apenas o `DISTFILES` do port estará disponível e somente via FTP/HTTP. Defina a variável `NO_CDROM` para uma string descrevendo o motivo pelo qual o port não pode ser redistribuído em CD-ROM. Por exemplo, use isto se a licença do port for somente para uso "não comercial". [[porting-restrictions-nofetchfiles]] === `NOFETCHFILES` Arquivos definidos em `NOFETCHFILES` não podem ser obtidos de nenhum dos `MASTER_SITES`. Um exemplo de tal tipo de arquivo é quando o arquivo é fornecido apenas em CD-ROM pelo fornecedor. Ferramentas que verificam a disponibilidade desses arquivos nos `MASTER_SITES` devem ignorar estes arquivos e não informar nada sobre eles. [[porting-restrictions-restricted]] === `RESTRICTED` Defina esta variável sozinha, se a licença do aplicativo não permitir o espelhamento do `DISTFILES` e nem a distribuição do pacote binário de forma alguma. Não defina as variáveis `NO_CDROM` ou `NO_PACKAGE` juntamente com a variável `RESTRICT`, uma vez que esta última variável implica as anteriores. Defina a variável `RESTRICTED` para uma string que descreva o motivo pelo qual o port não pode ser redistribuído. Normalmente, isso indica que o port contém software proprietário e que o usuário precisará baixar manualmente o `DISTFILES`, possivelmente após se registrar para ter acesso ao software ou após concordar em aceitar os termos de um EULA. [[porting-restrictions-restricted_files]] === `RESTRICTED_FILES` Quando a variável `RESTRICT` ou a `NO_CDROM` está definida, o valor padrão normalmente contém `${DISTFILES}${PATCHFILES}` caso contrário, ela fica vazia. Se apenas alguns dos arquivos da distribuição forem restritos, defina essa variável para listá-los. [[porting-restrictions-legal_text]] === `LEGAL_TEXT` Se o port tem preocupações legais as quais não foram abordadas pelas variáveis acima, defina a variável `LEGAL_TEXT` para uma string explicando a preocupação. Por exemplo, se o FreeBSD obteve uma permissão especial para redistribuir o binário, esta variável deve indicar isso. [[porting-restrictions-legal]] === [.filename]#/usr/ports/LEGAL# e `LEGAL` Um port que defina qualquer uma das variáveis ​​acima também deverá ser adicionado ao [.filename]#/usr/ports/LEGAL#. A primeira coluna é uma glob que corresponde aos distfiles restritos. A segunda coluna é a origem do port. A terceira coluna é a saída do comando `make -VLEGAL`. [[porting-restrictions-examples]] === Exemplos A maneira preferida de declarar "os distfiles para este port devem ser obtidos manualmente" é a seguinte: [.programlisting] .... .if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) IGNORE= may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR} .endif .... Isso tanto informa o usuário, quanto define os metadados apropriados na máquina do usuário para uso por programas automatizados. Note que esta estrofe deve ser precedida por uma inclusão de [.filename]#bsd.port.pre.mk#. [[building]] == Mecanismos de Compilação [[parallel-builds]] === Compilando Ports em Paralelo O framework de ports do FreeBSD suporta compilação paralela usando múltiplos subprocessos do comando `make`, o que permite que os sistemas SMP utilizem todo o poder disponível da CPU, permitindo que as compilações dos ports sejam mais rápidas e eficazes. Isso é alcançado passando-se a flag `-jX` para o man:make[1] executando no código do fornecedor. Este é o comportamento de compilação padrão dos ports. Infelizmente, nem todos os ports lidam bem com compilações paralelas e pode ser necessário desabilitar explicitamente esse recurso adicionando a variável `MAKE_JOBS_UNSAFE=yes`. Ela é usada quando um port é conhecido por não funcionar com a opção `-jX` devido a race conditions e problemas de compilação intermitentes. [IMPORTANT] ==== Ao definir a variável `MAKE_JOBS_UNSAFE`, é muito importante explicar com um comentário no [.filename]#Makefile#, ou pelo menos na mensagem de commit, _porque_ o port não pode ser compilado quando ela está ativa. Caso contrário, é quase impossível corrigir o problema ou testar se ele foi corrigido ao efetuar o commit de uma atualização em uma data posterior. ==== [[using-make]] === `make`, `gmake`, e `imake` Existem várias implementações diferentes do `make`. O software portado geralmente requer uma implementação específica, como o GNU `make`, conhecido no FreeBSD como `gmake`. Se o port usa o GNU make, adicione o `gmake` no `USES`. A variável `MAKE_CMD` pode ser usada para referenciar o comando específico configurado pelo `USES` no [.filename]#Makefile# do port. Use o `MAKE_CMD` apenas dentro dos [.filename]##Makefile##s do aplicativo no `WRKSRC` para chamar o comando `make` para a implementação esperada pelo software portado. -Se o port é um aplicativo X que usa o Imake para criar o [.filename]#Makefile# do [.filename]#Imakefile#, defina `USES=imake`. Veja a seção sobre <> no <> para mais detalhes. +Se o port é um aplicativo X que usa o Imake para criar o [.filename]#Makefile# do [.filename]#Imakefile#, defina `USES=imake`. Veja a seção sobre crossref:uses[uses-imake,`USES=imake`] no crossref:uses[uses,Usando Macros `USES`] para mais detalhes. Se o [.filename]#Makefile# do port tem algo diferente de `all` como o target de compilação principal, defina a variável `ALL_TARGET` adequadamente. O mesmo vale para `install` e `INSTALL_TARGET`. [[using-configure]] === Script `configure` Se o port usa o script `configure` para gerar [.filename]##Makefile##s a partir do [.filename]#Makefile.in# defina `GNU_CONFIGURE=yes`. Para dar argumentos extras ao script `configure` (o argumento padrão é `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir = ${MANPREFIX}/man --build = ${CONFIGURE_TARGET}`), defina estes argumentos extras em `CONFIGURE_ARGS`. Variáveis ​​de ambiente extras podem ser passadas usando `CONFIGURE_ENV`. [[using-configure-variables]] .Variáveis ​​para ports que usam o `configure` [cols="1,1", frame="none", options="header"] |=== | Variável | Significa |`GNU_CONFIGURE` |O port usa o script `configure` para preparar a construção. |`HAS_CONFIGURE` |Igual a `GNU_CONFIGURE`, exceto que o destino de configuração padrão não é adicionado a `CONFIGURE_ARGS`. |`CONFIGURE_ARGS` |Argumentos adicionais passados ​​para o script `configure`. |`CONFIGURE_ENV` |Variáveis de ambiente adicionais a serem definidas para execução de script `configure`. |`CONFIGURE_TARGET` |Substitui o target de configuração padrão. O valor padrão é `${MACHINE_ARCH}-portbld-freebsd${OSREL}`. |=== [[using-cmake]] === Usando o `cmake` Para ports que usam CMake, defina `USES=cmake`. [[using-cmake-variables]] .Variáveis ​​para ports que usam o `cmake` [cols="1,1", frame="none", options="header"] |=== | Variável | Significa |`CMAKE_ARGS` |Flags do CMake especificas para o port a serem passadas para o binário do `cmake`. |`CMAKE_ON` |Para cada entrada em `CMAKE_ON`, um valor booleano ativado é adicionado ao `CMAKE_ARGS`. Veja <>. |`CMAKE_OFF` |Para cada entrada em `CMAKE_OFF`, um valor booleano desativado é adicionado ao `CMAKE_ARGS`. Veja <>. |`CMAKE_BUILD_TYPE` |Tipo de compilação (perfis de compilação predefinidos para o CMake). O padrão é `Release` ou `Debug` se a variável `WITH_DEBUG` estiver definida. |`CMAKE_SOURCE_PATH` |Caminho para o diretório do fonte. O padrão é `${WRKSRC}`. |`CONFIGURE_ENV` |Variáveis ​​de ambiente adicionais a serem definidas para o binário do `cmake`. |=== [[using-cmake-user-variables]] .Variáveis ​​que os usuários podem definir para compilações com `cmake` [cols="1,1", frame="none", options="header"] |=== | Variável | Significa |`CMAKE_NOCOLOR` |Desativa o output colorido na compilação. Não é definido por padrão, a menos que `BATCH` ou `PACKAGE_BUILDING` esteja definido. |=== CMake suporta estes perfis de construção: `Debug`, `Release`, `RelWithDebInfo` e `MinSizeRel`. `Debug` e `Release` sistema de respeito de perfis `\*FLAGS`, `RelWithDebInfo` e `MinSizeRel` ajustará `CFLAGS` para `-O2 -g` e `-Os -DNDEBUG` correspondentemente. O valor do invólucro inferior `CMAKE_BUILD_TYPE` é exportado para `PLIST_SUB` e deve ser usado se o port for instalar [.filename]#*.cmake# dependendo do tipo de compilação (veja package:devel/kf5-kcrash[] por um exemplo). Por favor, note que alguns projetos podem definir seus próprios perfis de compilação e/ou forçar um tipo específico de compilação `CMAKE_BUILD_TYPE` dentro de [.filename]#CMakeLists.txt#. Para fazer um port para tal projeto respeite `CFLAGS` e `WITH_DEBUG`, as definições `CMAKE_BUILD_TYPE` devem ser removidas desses arquivos. A maioria dos projetos baseados em CMake suportam um método de compilação out-of-source. A compilação out-of-source de um port é a configuração padrão. Uma compilação in-source pode ser executada usando-se o sufixo `:insource`. Em uma compilação out-of-source, `CONFIGURE_WRKSRC`, `BUILD_WRKSRC` e `INSTALL_WRKSRC` serão definidos como `${WRKDIR}/.Build` e esse diretório será usado para manter todos os arquivos gerados durante os estágios de configuração e compilação, deixando o diretório de origem intacto. [[using-cmake-example]] .Exemplo de `USES=cmake` [example] ==== Este trecho demonstra o uso do CMake para um port. O `CMAKE_SOURCE_PATH` geralmente não é necessário, mas pode ser definido quando os fontes não estão localizados no diretório superior ou se apenas um subconjunto do projeto for compilado pelo port. [.programlisting] .... USES= cmake CMAKE_SOURCE_PATH= ${WRKSRC}/subproject .... ==== [[using-cmake-example2]] .`CMAKE_ON` and `CMAKE_OFF` [example] ==== Ao adicionar valores booleanos a variável `CMAKE_ARGS`, será mais fácil usar as variáveis `CMAKE_ON` e `CMAKE_OFF` ​​em vez disso. Desta forma: [.programlisting] .... CMAKE_ON= VAR1 VAR2 CMAKE_OFF= VAR3 .... É equivalente a: [.programlisting] .... CMAKE_ARGS= -DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE .... [IMPORTANT] ====== -Isto é apenas para os valores padrão desativados do `CMAKE_ARGS`. Os helpers descritos em <> usam a mesma semântica, mas para valores opcionais. +Isto é apenas para os valores padrão desativados do `CMAKE_ARGS`. Os helpers descritos em crossref:makefiles[options-cmake_bool,`OPT_CMAKE_BOOL` e `OPT_CMAKE_BOOL_OFF`] usam a mesma semântica, mas para valores opcionais. ====== ==== [[using-scons]] === Usando `scons` Se o port usa SCons, definir `USES=scons`. Para fazer os [.filename]#SConstruct# de terceiros respeitarem tudo o que é passado para SCons no ambiente (isto é, o mais importante, `CC/CXX/CFLAGS/CXXFLAGS`), altere o [.filename]#SConstruct# para que o `Evironment` de compilação fique da seguinte forma: [.programlisting] .... env = Environment(**ARGUMENTS) .... Ele poderá então ser modificado com `env.Append` e `env.Replace`. [[using-cargo]] === Compilando Aplicações Rust com `cargo` Para ports que usam Cargo, defina `USES=cargo`. [[using-cargo-user-variables]] .Variáveis ​​que os Usuários Podem Configurar para Compilar `cargo` [cols="1,1,1", frame="none", options="header"] |=== | Variável | Padrão | Descrição |`CARGO_CRATES` | |Lista de crates que o port depende. Cada entrada precisa ter um formato como `cratename-semver` por exemplo, `libc-0.2.40`. Os mantenedores de ports podem gerar essa lista a partir do [.filename]#Cargo.lock# usando o comando `make cargo-crates`. É possível alterar manualmente as versões dos crates, mas tenha em mente as dependências transitivas. |`CARGO_FEATURES` | |Lista de recursos do aplicativo a serem compilados (lista separada por espaço). Para desativar todos os recursos padrão, adicione o token especial `--no-default-features` para `CARGO_FEATURES`. Passar manualmente para `CARGO_BUILD_ARGS`, `CARGO_INSTALL_ARGS`, e `CARGO_TEST_ARGS` não é necessário. |`CARGO_CARGOTOML` |`${WRKSRC}/Cargo.toml` |O caminho para o [.filename]#Cargo.toml# que será usado. |`CARGO_CARGOLOCK` |`${WRKSRC}/Cargo.lock` |O caminho para o [.filename]#Cargo.lock# que será utilizado para o `make cargo-crates`. É possível especificar mais de um arquivo de bloqueio quando necessário. |`CARGO_ENV` | |Uma lista de variáveis ​​de ambiente para passar para o Cargo semelhante a `MAKE_ENV`. |`RUSTFLAGS` | |Flags para passar para o compilador Rust. |`CARGO_CONFIGURE` |`yes` |Use o padrão `do-configure`. |`CARGO_UPDATE_ARGS` | |Argumentos extras para passar para o Cargo durante a fase de configuração. Os argumentos válidos podem ser consultados com `cargo update --help`. |`CARGO_BUILDDEP` |`yes` |Adiciona uma dependência de compilação em package:lang/rust[]. |`CARGO_CARGO_BIN` |`${LOCALBASE}/bin/cargo` |Localização do binário do `cargo`. |`CARGO_BUILD` |`yes` |Use o padrão `do-build`. |`CARGO_BUILD_ARGS` | |Argumentos extras para passar para o Cargo durante a fase de compilação. Argumentos válidos podem ser consultados com `cargo buil --help`. |`CARGO_INSTALL` |`yes` |Use o padrão `do-install`. |`CARGO_INSTALL_ARGS` | |Argumentos extras para passar para o Cargo durante a fase de instalação. Os argumentos válidos podem ser consultados com `cargo isntall --help`. |`CARGO_INSTALL_PATH` |`.` |Caminho para o crate instalar. Isto é passado para o `cargo install` via argumento `--path`. Quando múltiplos caminhos são informados, o `cargo install` é executado múltiplas vezes. |`CARGO_TEST` |`yes` |Use o padrão `do-test`. |`CARGO_TEST_ARGS` | |Argumentos extras para passar para o Cargo durante a fase de teste. Os argumentos válidos podem ser consultados com `cargo test --help`. |`CARGO_TARGET_DIR` |`${WRKDIR}/target` |Localização do diretório de saída do cargo. |`CARGO_DIST_SUBDIR` |[.filename]#rust/crates# |Diretório relativo a `DISTDIR` onde os arquivos de distribuição do crate serão armazenados. |`CARGO_VENDOR_DIR` |`${WRKSRC}/cargo-crates` |Localização do diretório do fornecedor onde todas os crates serão extraídos. Tente manter isto sob `PATCH_WRKSRC`, para que os patches possam ser aplicados facilmente. |`CARGO_USE_GITHUB` |`no` |Ativa a busca de crates bloqueadas para commits específicos do Git no GitHub via `GH_TUPLE`. Isso tentará modificar o [.filename]#Cargo.toml# no `WRKDIR` para apontar para os fontes offline, em vez de buscá-los em um repositório Git durante a compilação. |`CARGO_USE_GITLAB` |`no` |O mesmo que `CARGO_USE_GITHUB` mas para instâncias GitLab e `GL_TUPLE`. |=== [[cargo-ex1]] .Criando um Port para uma Aplicação Simples em Rust [example] ==== Criar um port baseado em cargo é um processo de três estágios. Primeiro, precisamos fornecer um modelo de port que busque o arquivo de distribuição do aplicativo: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower .include .... Gerar uma [.filename]#distinfo# inicial: [source,shell] .... % make makesum => Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s .... Agora o arquivo de distribuição está pronto para uso e podemos ir em frente e extrair as dependências crate do pacote [.filename]#Cargo.lock#: [source,shell] .... % make cargo-crates CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .... A saída deste comando precisa ser colada diretamente no Makefile: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .include .... O [.filename]#distinfo# precisa ser regenerado para conter todos os arquivos de distribuição dos crates: [source,shell] .... % make makesum => rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s => rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s => rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s => rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s => rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/. [...] .... O port está agora pronto para uma compilação de teste e ajustes adicionais, como criar um plist, escrever uma descrição, adicionar informações de licença, opções, etc. como é normal. Se você não estiver testando seu port em um ambiente limpo, como com o Poudriere, lembre-se de executar `make clean` antes de qualquer teste. ==== [[cargo-ex2]] .Ativando Recursos Adicionais do Aplicativo [example] ==== Alguns aplicativos definem recursos adicionais em seus [.filename]#Cargo.toml#. Eles podem ser compilados definindo a variável `CARGO_FEATURES` no port. Aqui nós habilitamos as features Tokei's `json` e `yaml`: [.programlisting] .... CARGO_FEATURES= json yaml .... ==== [[cargo-ex4]] .Features de Codificação de Aplicativos como Opções de Port [example] ==== Um exemplo de seção `[features]` no [.filename]#Cargo.toml# pode parecer assim: [.programlisting] .... [features] pulseaudio_backend = ["librespot-playback/pulseaudio-backend"] portaudio_backend = ["librespot-playback/portaudio-backend"] default = ["pulseaudio_backend"] .... `pulseaudio_backend` é uma feature padrão. Ela está sempre ativada, a menos que desativemos explicitamente os recursos padrão adicionando `--no-default-features` para o `CARGO_FEATURES`. Aqui nós mudamos as features `portaudio_backend` e `pulseaudio_backend` em opções de port: [.programlisting] .... CARGO_FEATURES= --no-default-features OPTIONS_DEFINE= PORTAUDIO PULSEAUDIO PORTAUDIO_VARS= CARGO_FEATURES+=portaudio_backend PULSEAUDIO_VARS= CARGO_FEATURES+=pulseaudio_backend .... ==== [[cargo-ex3]] .Listando Licenças Crate [example] ==== -Os crates têm suas próprias licenças. É importante saber o que elas são ao adicionar o bloco `LICENSE` para o port (ver<>). O target auxiliar `cargo-crates-licenses` tentará listar todas as licenças de todos os crates definidos no `CARGO_CRATES`. +Os crates têm suas próprias licenças. É importante saber o que elas são ao adicionar o bloco `LICENSE` para o port (ver crossref:makefiles[licenses,Licenças]). O target auxiliar `cargo-crates-licenses` tentará listar todas as licenças de todos os crates definidos no `CARGO_CRATES`. [source,shell] .... % make cargo-crates-licenses aho-corasick-0.6.4 Unlicense/MIT ansi_term-0.11.0 MIT arrayvec-0.4.7 MIT/Apache-2.0 atty-0.2.9 MIT bitflags-1.0.1 MIT/Apache-2.0 byteorder-1.2.2 Unlicense/MIT [...] .... [NOTE] ====== -Os nomes das licenças geradas com `make cargo-create-licenses` são expressões de licenças do SPDX 2.1 que não correspondem aos nomes de licença definidos na estrutura de ports. Eles precisam ser traduzidos para os nomes de <>. +Os nomes das licenças geradas com `make cargo-create-licenses` são expressões de licenças do SPDX 2.1 que não correspondem aos nomes de licença definidos na estrutura de ports. Eles precisam ser traduzidos para os nomes de crossref:makefiles[licenses-license-list, Lista de Licenças Predefinidas]. ====== ==== [[using-meson]] === Usando `meson` Para ports que usam Meson, defina `USES=meson`. [[using-meson-variables]] .Variáveis ​​para ports que usam o `meson` [cols="1,1", frame="none", options="header"] |=== | Variável | Descrição |`MESON_ARGS` |Flags do Meson especificas para o port a serem passadas para o binário do `meson`. |`MESON_BUILD_DIR` |Caminho para o diretório de compilação relativo ao `WRKSRC`. O padrão é `_build`. |=== [[using-meson-example]] .Exemplo de `USES=meson` [example] ==== Este trecho demonstra o uso do Meson para um port. [.programlisting] .... USES= meson MESON_ARGS= -Dfoo=enabled .... ==== [[using-go]] === Compilando Aplicações Go -Para ports que usam Go, defina `USES=go`. Consulte <> para obter a lista de variáveis que podem ser configuradas para controlar o processo de compilação. +Para ports que usam Go, defina `USES=go`. Consulte crossref:uses[uses-go,`go`] para obter a lista de variáveis que podem ser configuradas para controlar o processo de compilação. [[go-ex1]] .Criando um Port para uma Aplicação Baseada em Módulos Go [example] ==== Criar um port baseado em Go é um processo de cinco estágios. Primeiro, precisamos fornecer um modelo de port que baixa o arquivo de distribuição do aplicativo: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy USES= go:modules USE_GITHUB= yes GH_ACCOUNT= motemen .include .... Gerar uma [.filename]#distinfo# inicial: [source,shell] .... % make makesum ===> License MIT accepted by the user => motemen-ghq-v0.12.5_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz fetch: https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz: size of remote file is not known motemen-ghq-v0.12.5_GH0.tar.gz 32 kB 177 kBps 00s .... Agora o arquivo de distribuição está pronto para uso e podemos extrair as dependências necessárias de módulos Go. Esta etapa requer a instalação do package:ports-mgmt/modules2tuple[]: [source,shell] .... % make gomod-vendor [...] GH_TUPLE= \ Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .... A saída deste comando precisa ser colada diretamente no Makefile: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy USES= go:modules USE_GITHUB= yes GH_ACCOUNT= motemen GH_TUPLE= Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .include .... O [.filename]#distinfo# precisa ser gerado novamente para conter todos os arquivos de distribuição: [source,shell] .... % make makesum => Songmu-gitconfig-v0.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz fetch: https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz: size of remote file is not known Songmu-gitconfig-v0.0.2_GH0.tar.gz 5662 B 936 kBps 00s => daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz fetch: https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz: size of remote file is not known daviddengcn-go-colortext-186a3d44e920_GH0.tar. 4534 B 1098 kBps 00s [...] .... O port está agora pronto para uma compilação de teste e ajustes adicionais, como criar um plist, escrever uma descrição, adicionar informações de licença, opções, etc. como é normal. Se você não estiver testando seu port em um ambiente limpo, como com o Poudriere, lembre-se de executar `make clean` antes de qualquer teste. ==== [[go-ex2]] .Definindo o Nome do Binário ou o Caminho da Instalação [example] ==== Alguns ports precisam instalar o binário resultante com um nome diferente ou em um caminho diferente do padrão `${PREFIX}/bin`. Isso pode ser feito usando a sintaxe de tupla `GO_TARGET`, por exemplo: [.programlisting] .... GO_TARGET= ./cmd/ipfs:ipfs-go .... irá instalar o binário `ipfs` como `${PREFIX}/bin/ipfs-go` e [.programlisting] .... GO_TARGET= ./dnscrypt-proxy:${PREFIX}/sbin/dnscrypt-proxy .... irá instalar `dnscrypt-proxy` em `${PREFIX}/sbin`. ==== [[using-cabal]] === Compilando Aplicações Haskell com `cabal` -Para ports que usam Cabal, defina o sistema de compilação `USES=cabal`. Consulte <> para obter a lista de variáveis que podem ser configuradas para controlar o processo de compilação. +Para ports que usam Cabal, defina o sistema de compilação `USES=cabal`. Consulte crossref:uses[uses-cabal,`cabal`] para obter a lista de variáveis que podem ser configuradas para controlar o processo de compilação. [[cabal-ex1]] .Criando um Port para uma Aplicação Hackage-hosted Haskell [example] ==== Ao preparar um port Haskell Cabal, o programa package:devel/hs-cabal-install[] é necessário, portanto, certifique-se de que esteja instalado previamente. Primeiro, precisamos definir variáveis de ports comuns que permitem ao cabal-install buscar o arquivo de distribuição de pacotes: [.programlisting] .... PORTNAME= ShellCheck DISTVERSION= 0.6.0 CATEGORIES= devel MAINTAINER= haskell@FreeBSD.org COMMENT= Shell script analysis tool USES= cabal .include .... Esse Makefile mínimo nos permite baixar o arquivo de distribuição: [source,shell] .... % make cabal-extract [...] Downloading the latest package list from hackage.haskell.org cabal get ShellCheck-0.6.0 Downloading ShellCheck-0.6.0 Downloaded ShellCheck-0.6.0 Unpacking to ShellCheck-0.6.0/ .... Agora, temos o arquivo de descrição do pacote ShellCheck.cabal, que permite baixar todas as dependências do pacote, incluindo as transitivas: [source,shell] .... % make cabal-extract-deps [...] Resolving dependencies... Downloading base-orphans-0.8.2 Downloaded base-orphans-0.8.2 Downloading primitive-0.7.0.0 Starting base-orphans-0.8.2 (lib) Building base-orphans-0.8.2 (lib) Downloaded primitive-0.7.0.0 Downloading dlist-0.8.0.7 [...] .... Como efeito colateral, as dependências do pacote também são compiladas, portanto, o comando pode levar algum tempo. Uma vez feito, uma lista de dependências necessárias pode ser gerada: [source,shell] .... % make make-use-cabal USE_CABAL=QuickCheck-2.12.6.1 \ hashable-1.3.0.0 \ integer-logarithms-1.0.3 \ [...] .... Pacotes Haskell podem conter revisões, assim como nos ports do FreeBSD. As revisões podem afetar apenas os arquivos [.filename]#.cabal#, mas ainda é importante extraí-los. Para verificar os itens `USE_CABAL` quanto a atualizações de revisão disponíveis, execute o seguinte comando: [source,shell] .... % make make-use-cabal-revs USE_CABAL=QuickCheck-2.12.6.1_1 \ hashable-1.3.0.0 \ integer-logarithms-1.0.3_2 \ [...] .... Observe os números de versão adicionais após o símbolo `_`. Coloque a lista `USE_CABAL` recém-gerada em vez de uma antiga. Finalmente, o [.filename]#distinfo# precisa ser gerado novamente para conter todos os arquivos de distribuição: [source,shell] .... % make makesum => ShellCheck-0.6.0.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/ShellCheck-0.6.0/ShellCheck-0.6.0.tar.gz ShellCheck-0.6.0.tar.gz 136 kB 642 kBps 00s => QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 65 kB 361 kBps 00s [...] .... O port está agora pronto para uma compilação de teste e ajustes adicionais, como criar um plist, escrever uma descrição, adicionar informações de licença, opções, etc. como é normal. Se você não estiver testando seu port em um ambiente limpo, como com o Poudriere, lembre-se de executar `make clean` antes de qualquer teste. ==== [[using-autotools]] == Usando o GNU Autotools -Se um port precisar de algum software GNU Autotools, adicione `USES=autoreconf`. Veja <> Para maiores informações. +Se um port precisar de algum software GNU Autotools, adicione `USES=autoreconf`. Veja crossref:uses[uses-autoreconf,`autoreconf`] Para maiores informações. [[using-gettext]] == Usando o GNU `gettext` [[using-gettext-basic]] === Uso Básico -Se o port requer o `gettext`, defina `USES=gettext`, e o port herdará a dependência [.filename]#libintl.so# do package:devel/gettext[]. Outros valores para uso do `gettext` estão listados em <>. +Se o port requer o `gettext`, defina `USES=gettext`, e o port herdará a dependência [.filename]#libintl.so# do package:devel/gettext[]. Outros valores para uso do `gettext` estão listados em crossref:uses[uses-gettext,`USES=gettext`]. Um caso bastante comum é um port que utilize o `gettext` e o `configure`. Geralmente, o GNU `configure` deve ser capaz de localizar o `gettext` automaticamente. [.programlisting] .... USES= gettext GNU_CONFIGURE= yes .... Se falhar, dicas da localização do `gettext` podem ser informados por meio do `CPPFLAGS` e LDFLAGS` utilizando `localbase` do seguinte modo: [.programlisting] .... USES= gettext localbase:ldflags GNU_CONFIGURE= yes .... [[using-gettext-optional]] === Uso Opcional Alguns softwares permitem desabilitar o NLS. Por exemplo, passando `--disable-nls` para o `configure`. Nesse caso, o port deve usar `gettext` condicionalmente, dependendo do status da opção `NLS`. Para ports de baixa a média complexidade, use este idioma: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS OPTIONS_SUB= yes NLS_USES= gettext NLS_CONFIGURE_ENABLE= nls .include .... Ou usando a maneira antiga de usar opções: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS .include .if ${PORT_OPTIONS:MNLS} USES+= gettext PLIST_SUB+= NLS="" .else CONFIGURE_ARGS+= --disable-nls PLIST_SUB+= NLS="@comment " .endif .include .... O próximo item na lista de tarefas a fazer é organizar de forma condicional os arquivos do catálogo de mensagens na lista de pacotes. A parte do [.filename]#Makefile# desta tarefa já é fornecida pela expressão idiomática. Isto é explicado na seção sobre <>. Em poucas palavras, cada ocorrência de `%%NLS%%` dentro de [.filename]#pkg-plist# será substituído por "`@comment`" se o NLS estiver desativado ou por uma cadeia nula se o NLS estiver ativado. Consequentemente, as linhas prefixadas por `%%NLS%%` se tornarão meros comentários na lista de empacotamento final se o NLS estiver desativado; caso contrário, o prefixo será deixado de fora. Em seguida, insira `%%NLS%%` antes de cada caminho para um arquivo de catálogo de mensagens em [.filename]#pkg-plist#. Por exemplo: [.programlisting] .... %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo .... Em casos de alta complexidade, técnicas mais avançadas podem ser necessárias, como <>. [[using-gettext-catalog-directories]] === Manipulando Diretórios do Catálogo de Mensagens Há um ponto a ser observado sobre a instalação de arquivos de catálogo de mensagens. Os diretórios de destino para eles, que residem em [.filename]#LOCALBASE/shared/locale#, não devem ser criados e removidos por um port. Os idiomas mais populares têm seus respectivos diretórios listados em [.filename]#PORTSDIR/Templates/BSD.local.dist#. Os diretórios para muitos outros idiomas são governados pelo port package:devel/gettext[]. Consulte o seu [.filename]#pkg-plist# e veja se o port vai instalar um arquivo de catálogo de mensagens para um idioma exclusivo. [[using-perl]] == Usando Perl E se o `MASTER_SITES` estiver configurado para `CPAN`, o subdiretório correto é geralmente selecionado automaticamente. Se o subdiretório padrão estiver errado, o `CPAN/Module` pode ser usado para alterá-lo. O `MASTER_SITES` também pode ser definido para o antigo `MASTER_SITE_PERL_CPAN`, então o valor preferido para o `MASTER_SITE_SUBDIR` é o nome da hierarquia de nível superior. Por exemplo, o valor recomendado para `p5-Module-Name` é `Module`. A hierarquia de nível superior pode ser examinada em http://cpan.org/modules/by-module/[cpan.org]. Isso mantém o port funcionando quando o autor do módulo muda. A exceção a essa regra é quando o diretório relevante não existe ou o distfile não existe neste diretório. Neste caso, é permitido usar o id do autor como `MASTER_SITE_SUBDIR`. A macro `CPAN: AUTOR` pode ser usada, a qual será traduzida para o diretório de autor com hash. Por exemplo,`CPAN: AUTOR` será convertido para `autores/id/A/AU/AUTOR`. Quando um port precisa de suporte a Perl, ele deve definir `USES=perl5` com o opcional `USE_PERL5` descrito em <>. [[using-perl-variables]] .Variáveis ​​Somente Leitura para Ports Que Usam Perl [cols="1,1", frame="none", options="header"] |=== | Variáveis ​​Somente de Leitura | Significa |`PERL` |O caminho completo do interpretador Perl 5, seja no sistema ou instalado a partir de um port, mas sem o número da versão. Use isso quando o software precisar do caminho para o interpretador Perl. Para substituir as linhas "`#!`" em scripts, use <>. |`PERL_VERSION` |A versão completa do Perl instalada (por exemplo, `5,8,9`). |`PERL_LEVEL` |A versão do Perl instalada como um inteiro no formato `MNNNPP` (por exemplo,`500809`). |`PERL_ARCH` |Local no qual o Perl armazena as bibliotecas dependentes da arquitetura. O valor padrão aponta para `${ARCH}-freebsd`. |`PERL_PORT` |Nome do port Perl instalado (por exemplo,`perl5`). |`SITE_PERL` |Nome do diretório para onde vão os pacotes Perl específicos do site. Esse valor é adicionado a `PLIST_SUB`. |=== [NOTE] ==== Ports de Módulos Perl que não possuem um site oficial devem linkar para `cpan.org` na linha WWW do [.filename]#pkg-descr#. O formato preferido para a URL é `http://search.cpan.org/dist/Module-Name/` (incluindo a barra final). ==== [NOTE] ==== Não use `${SITE_PERL}` em declarações de dependência. Fazê-lo pressupõe que o [.filename]#perl5.mk# foi incluído, o que nem sempre é verdade. Os ports que dependem desse port terão dependências incorretas se os arquivos desse port forem movidos posteriormente em uma atualização. O caminho certo para declarar as dependências do módulo Perl é mostrado no exemplo abaixo. ==== [[use-perl-dependency-example]] .Exemplo de Dependência Perl [example] ==== [.programlisting] .... p5-IO-Tee>=0.64:devel/p5-IO-Tee .... ==== Para ports Perl que instalam páginas de manual, as macros `PERL5_MAN3` e `PERL5_MAN1` podem ser usadas dentro do [.filename]#pkg-plist#. Por exemplo, [.programlisting] .... lib/perl5/5.14/man/man1/event.1.gz lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz .... pode ​​ser substituído por [.programlisting] .... %%PERL5_MAN1%%/event.1.gz %%PERL5_MAN3%%/AnyEvent::I3.3.gz .... [NOTE] ==== Não existem macros `PERL5_MANx` para as outras seções (sendo _x_ igual a `2` e de `4` até `9`) porque estes são instalados nos diretórios comuns. ==== [[use-perl-ex-build]] .Um Port Que Requer Perl Apenas para Compilar [example] ==== Como o valor padrão para USE_PERL5 é build e run, configure-o para: [.programlisting] .... USES= perl5 USE_PERL5= build .... ==== [[use-perl-ex-patch]] .Um Port Que Também Requer Perl Para Patch [example] ==== De tempos em tempos, o uso do man:sed[1] para patches se torna insuficiente. Quando usar man:perl[1] fica mais facil, para isso utilize: [.programlisting] .... USES= perl5 USE_PERL5= patch build run .... ==== [[use-perl-ex-configure]] .Um Módulo Perl Que Precisa de `ExtUtils::MakeMaker` para Compilar [example] ==== A maioria dos módulos Perl vêm com um script configure [.filename]#Makefile.PL#. Neste caso, defina: [.programlisting] .... USES= perl5 USE_PERL5= configure .... ==== [[use-perl-ex-modbuild]] .Um Módulo Perl Que Precisa `Módulo::Build` para Compilar [example] ==== Quando um modulo Perl vem com um script configure [.filename]#Build.PL#, pode exigir Module:Build, nesse caso, defina [.programlisting] .... USES= perl5 USE_PERL5= modbuild .... Se for ao contrário, e exigir Module::Build::Tiny, defina [.programlisting] .... USES= perl5 USE_PERL5= modbuildtiny .... ==== [[using-x11]] == Usando o X11 [[x11-variables]] === Componentes X.Org -A implementação do X11 disponível na Coleção de Ports é o X.Org. Se o aplicativo depender de componentes X, adicione `USES= xorg` e defina `USE_XORG` na lista de componentes necessários. Uma lista completa pode ser encontrada em <>. +A implementação do X11 disponível na Coleção de Ports é o X.Org. Se o aplicativo depender de componentes X, adicione `USES= xorg` e defina `USE_XORG` na lista de componentes necessários. Uma lista completa pode ser encontrada em crossref:uses[uses-xorg,`xorg`]. -O Projeto Mesa é um esforço para fornecer implementação gratuita do OpenGL. Para especificar uma dependência em vários componentes deste projeto, use a variável `USE_GL`. Veja <> para a lista completa dos componentes disponíveis. Para compatibilidade com versões anteriores, o valor `yes` direciona para `glu`. +O Projeto Mesa é um esforço para fornecer implementação gratuita do OpenGL. Para especificar uma dependência em vários componentes deste projeto, use a variável `USE_GL`. Veja crossref:uses[uses-gl,`gl`] para a lista completa dos componentes disponíveis. Para compatibilidade com versões anteriores, o valor `yes` direciona para `glu`. [[use-xorg-example]] .Exemplo `USE_XORG` [example] ==== [.programlisting] .... USES= gl xorg USE_GL= glu USE_XORG= xrender xft xkbfile xt xaw .... ==== [[using-xorg-variables]] .Variáveis ​​para Ports Que Usam X [cols="1,1", frame="none"] |=== |`USES= imake` |O port usa `imake`. |`XMKMF` |Definir o caminho de `xmkmf` se não no `PATH`. Padrão para `xmkmf -a`. |=== [[using-x11-vars]] .Usando Variáveis ​​Relacionadas ao X11 [example] ==== [.programlisting] .... # Use some X11 libraries USES= xorg USE_XORG= x11 xpm .... ==== [[x11-motif]] === Ports que Requerem Motif Se o port requer uma biblioteca Motif, defina `USES=motif` no [.filename]#Makefile#. A implementação padrão do Motif é package:x11-toolkits/open-motif[]. Os usuários podem escolher o package:x11-toolkits/lesstif[] em vez disso, definindo `WANT_LESSTIF` no seu [.filename]#make.conf#. O `MOTIFLIB` será definido por [.filename]#motif.mk# para referenciar a biblioteca Motif apropriada. Por favor, corrija o fonte do port para usar `${MOTIFLIB}` onde quer que a biblioteca Motif seja referenciada no [.filename]#Makefile# original ou no [.filename]#Imakefile#. Existem dois casos comuns: * Se o port se referir à biblioteca Motif como `-lXm` em seu [.filename]#Makefile# ou [.filename]#Imakefile#, substitua `${MOTIFLIB}` por isso. * Se o port usa `XmClientLibs` em seu [.filename]#Imakefile#, mude para `${MOTIFLIB} ${XTOOLLIB} ${XLIB}`. Observe que o `MOTIFLIB` (geralmente) se expande para `-L/usr/local/lib -lXm -lXp` ou `/usr/local/lib/libXm.a`, então não há necessidade de adicionar `-L` ou `-l` na frente. [[x11-fonts]] === Fontes X11 Se o port instalar fontes para o X Window System, coloque-as em [.filename]#LOCALBASE/lib/X11/fontes/local#. [[x11-fake-display]] === Obtendo um `DISPLAY` Falso com Xvfb Algumas aplicações requerem uma tela X11 funcional para que a compilação seja bem-sucedida. Isso representa um problema para as máquinas que operam sem um monitor. Quando essa variável é usada, a infraestrutura de compilação iniciará o X virtual framebuffer. Um `DISPLAY` funcional é então passado para a compilação. Veja <> para os possíveis argumentos. [.programlisting] .... USES= display .... [[desktop-entries]] === Entradas de Desktop Entradas de desktop (http://standards.freedesktop.org/desktop-entry-spec/latest/[um padrão Freedesktop]) fornecem uma maneira de ajustar automaticamente os recursos do desktop quando um novo programa é instalado, sem a necessidade de intervenção do usuário. Por exemplo, programas recém-instalados aparecem automaticamente nos menus de aplicativos de ambientes de desktop compatíveis. Entradas de Desktop surgiram no ambiente de desktop GNOME, mas agora são um padrão e também funcionam com o KDE e o Xfce. Esta pitada de automação fornece um benefício real para o usuário, e as entradas de desktop são incentivadas para aplicativos que podem ser usados em um ambiente desktop. [[desktop-entries-predefined]] ==== Usando Arquivos [.filename]#.desktop# Pré-definidos Ports que incluem [.filename]#*.desktop# pré-definidos devem incluir estes arquivos no [.filename]#pkg-plist# e instalá-los no diretório [.filename]#$LOCALBASE/shared/applications#. A macro <> é útil para instalar esses arquivos. [[updating-desktop-database]] ==== Atualizando o Banco de Dados do Desktop Se um port tiver uma entrada MimeType em seu [.filename]#portname.desktop#, o banco de dados do desktop deve ser atualizado após a instalação e desinstalação. Para fazer isso, defina `USES`= desktop-file-utils. [[desktop-entries-macro]] ==== Criando Entradas de Desktop com `DESKTOP_ENTRIES` As entradas desktop podem ser facilmente criadas para aplicativos usando `DESKTOP_ENTRIES`. Um arquivo chamado [.filename]#name.desktop# será criado, instalado e adicionado ao [.filename]#pkg-plist# automaticamente. A sintaxe é: [.programlisting] .... DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify .... A lista de possíveis categorias está disponível no http://standards.freedesktop.org/menu-spec/latest/apa.html[Site Freedesktop]. `StartupNotify` indica se a aplicação é compatível com _notificações de inicialização_. Estes são tipicamente um indicador gráfico como um relógio que aparece no ponteiro do mouse, menu ou painel para dar ao usuário uma indicação quando um programa está sendo iniciado. Um programa que seja compatível com as notificações de inicialização limpa o indicador depois de iniciado. Programas que não são compatíveis com as notificações de inicialização nunca limpariam o indicador (possivelmente confundindo e enfurecendo o usuário) e devem ter `StartupNotify` definido como `false` então o indicador não é mostrado. Exemplo: [.programlisting] .... DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ "${DATADIR}/xtra/graf/tome-128.png" \ "tome -v -g" "Application;Game;RolePlaying;" \ false .... [[using-gnome]] == Usando o GNOME [[using-gnome-introduction]] === Introdução Este capítulo explica a estrutura do framework GNOME utilizado pelos ports. O framework pode ser dividido livremente nos componentes base, componentes desktop GNOME e algumas macros especiais que simplificam o trabalho dos mantenedores dos ports. [[use-gnome]] === Usando `USE_GNOME` Adicionar esta variável ao port permite o uso das macros e componentes definidos em [.filename]#bsd.gnome.mk#. O código em [.filename]#bsd.gnome.mk# adiciona as dependências de tempo de compilação, tempo de execução ou biblioteca necessárias ou o tratamento de arquivos especiais. Aplicativos GNOME sob o FreeBSD usam o framework `USE_GNOME`. Inclua todos os componentes necessários como uma lista separada por espaço. Os componentes `USE_GNOME` são divididos nessas listas virtuais: componentes básicos, componentes do GNOME 3 e componentes legados. Se o port precisa apenas de bibliotecas GTK3, este é o caminho mais curto para defini-lo: [.programlisting] .... USE_GNOME= gtk30 .... Componentes `USE_GNOME` adicionam automaticamente as dependências de que precisam. Por favor, veja <>para uma lista exaustiva de todos componentes `USE_GNOME` e quais outros componentes eles implicam e suas dependências. Aqui está um exemplo de [.filename]#Makefile# para um port do GNOME que usa muitas das técnicas descritas neste documento. Por favor, use-o como um guia para criar novos ports. [.programlisting] .... # $FreeBSD$ PORTNAME= regexxer DISTVERSION= 0.10 CATEGORIES= devel textproc gnome MASTER_SITES= GNOME MAINTAINER= kwm@FreeBSD.org COMMENT= Interactive tool for performing search and replace operations USES= gettext gmake localbase:ldflags pathfix pkgconfig tar:xz GNU_CONFIGURE= yes USE_GNOME= gnomeprefix intlhack gtksourceviewmm3 INSTALLS_ICONS= yes GLIB_SCHEMAS= org.regexxer.gschema.xml .include .... [NOTE] ==== A macro `USE_GNOME` se utilizada sem nenhum argumento não irá adicionar nenhuma dependência ao port. O `USE_GNOME` não pode ser definido depois do [.filename]#bsd.port.pre.mk#. ==== [[using-gnome-variables]] === Variáveis Esta seção explica quais macros estão disponíveis e como elas são usadas. Como elas são usadas no exemplo acima. A <> tem uma explicação mais detalhada. A variável `USE_GNOME` precisa ser definido para que essas macros sejam úteis. `INSTALLS_ICONS`:: Ports GTK+ que instalam ícones de estilo Freedesktop em [.filename]#${LOCALBASE}/shared/icons# deve usar essa macro para garantir que os ícones sejam armazenados em cache e exibidos corretamente. O arquivo de cache é nomeado [.filename]#icon-theme.cache#. Não inclua esse arquivo em [.filename]#pkg-plist#. Essa macro manipula isso automaticamente. Esta macro não é necessária para Qt, que usam um método interno. `GLIB_SCHEMAS`:: Lista de todos os arquivos de esquema de glib que o port instala. A macro adicionará os arquivos ao plist do port e manipulará o registro destes arquivos na instalação e desinstalação. + Os arquivos de esquema do glib são escritos em XML e terminam com a extensão [.filename]#gschema.xml#. Eles estão instalados no diretório [.filename]#share/glib-2.0/schemas/#. Esses arquivos de esquema contêm todos os valores de configuração do aplicativo com as configurações padrão. O banco de dados real usado pelos aplicativos é construído por glib-compile-schema, que é executado pela macro `GLIB_SCHEMAS`. + [.programlisting] .... GLIB_SCHEMAS=foo.gschema.xml .... + [NOTE] ==== Não adicione esquemas simplificados ao [.filename]#pkg-plist#. Se eles estão listados em [.filename]#pkg-plist#, eles não serão registrados e os aplicativos podem não funcionar corretamente. ==== `GCONF_SCHEMAS`:: Liste todos os arquivos do esquema gconf. A macro adicionará os arquivos de esquema ao plist do port e manipulará seu registro na instalação e desinstalação. + O GConf é o banco de dados baseado em XML que praticamente todos os aplicativos GNOME usam para armazenar suas configurações. Esses arquivos são instalados no banco de dados no diretório [.filename]#etc/gconf/schemas#. Esse banco de dados é definido pelos arquivos de esquema instalados que são usados para gerar os arquivos chave [.filename]#%gconf.xml#. Para cada arquivo de esquema instalado pelo port, deve existir uma entrada no [.filename]#Makefile#: + [.programlisting] .... GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas .... + [NOTE] ==== Os esquemas do Gconf estão listados na macro `GCONF_SCHEMAS` em vez do [.filename]#pkg-plist#. Se eles estiverem listados em [.filename]#pkg-plist#, eles não serão registrados e os aplicativos podem não funcionar corretamente. ==== `INSTALLS_OMF`:: Os arquivos do Open Source Metadata Framework (OMF) são comumente usados ​​pelos aplicativos GNOME 2. Esses arquivos contêm as informações do arquivo de ajuda do aplicativo e requerem processamento especial pelo ScrollKeeper/rarian. Para registrar adequadamente arquivos OMF ao instalar aplicativos GNOME a partir de pacotes, certifique-se de que os arquivos `omf` estão listados em `pkg-plist` e que o [.filename]#Makefile# do port tem o `INSTALLS_OMF` definido: + [.programlisting] .... INSTALLS_OMF=yes .... + Quando definido, [.filename]#bsd.gnome.mk# digitaliza automaticamente o [.filename]#pkg-plist# e adiciona diretivas `@exec` e `@unexec` para cada [.filename]#.omf# para rastrear no banco de dados de registro do OMF. [[gnome-components]] == Componentes GNOME Para mais ajuda com um port GNOME, veja alguns dos https://www.FreeBSD.org/ports/gnome/[ports existentes] por exemplo. A pagina https://www.FreeBSD.org/gnome/[ GNOME do FreeBSD] tem informações de contato, se precisar de mais ajuda. Os componentes são divididos em componentes GNOME que estão atualmente em uso e componentes legados. Se o componente suportar argumento, eles serão listados entre parênteses na descrição. O primeiro é o padrão. "Ambos" são mostrados se o componente usar como padrão a adição às dependências de construção e execução. [[gnome-components-list]] .Componentes GNOME [cols="1,1,1", options="header"] |=== | Componente | Programa associado | Descrição |`atk` |accessibility/atk |Kit de ferramentas de acessibilidade (ATK) |`atkmm` |accessibility/atkmm |c++ bindings para atk |`cairo` |graphics/cairo |Biblioteca de gráficos vetoriais com suporte a saída entre dispositivos |`cairomm` |graphics/cairomm |c++ bindings para o cairo |`dconf` |devel/dconf |Sistema de banco de dados de configuração (both, buil, run) |`evolutiondataserver3` |databases/evolution-data-server |Backends de dados para a suíte mail/PIM integrada do Evolution |`gdkpixbuf2` |graphics/gdk-pixbuf2 |Biblioteca de gráficos para GTK+ |`glib20` |devel/glib20 |Biblioteca core do GNOME `glib20` |`glibmm` |devel/glibmm |c++ bindings para glib20 |`gnomecontrolcenter3` |sysutils/gnome-control-center |Centro de Controle do GNOME 3 |`gnomedesktop3` |x11/gnome-desktop |Biblioteca de interface do usuário do desktop GNOME 3 |`gsound` |audio/gsound |Biblioteca GObject para reproduzir sons do sistema (both, build, run) |`gtk-update-icon-cache` |graphics/gtk-update-icon-cache |Utilitário Gtk-update-icon-cache do kit de ferramentas Gtk + |`gtk20` |x11-toolkits/gtk20 |Kit de ferramentas Gtk+ 2 |`gtk30` |x11-toolkits/gtk30 |Kit de ferramentas Gtk+ 3 |`gtkmm20` |x11-toolkits/gtkmm20 |c++ bindings 2.0 para o kit de ferramentas gtk20 |`gtkmm24` |x11-toolkits/gtkmm24 |c++ bindings 2.4 para o kit de ferramentas gtk20 |`gtkmm30` |x11-toolkits/gtkmm30 |c++ bindings 3.0 para o kit de ferramentas gtk30 |`gtksourceview2` |x11-toolkits/gtksourceview2 |Widget que adiciona destaque de sintaxe para o GtkTextView |`gtksourceview3` |x11-toolkits/gtksourceview3 |Widget de texto que adiciona destaque de sintaxe ao widget GtkTextView |`gtksourceviewmm3` |x11-toolkits/gtksourceviewmm3 |c++ bindings para a biblioteca gtksourceview3 |`gvfs` |devel/gvfs |Sistema de arquivos virtual do GNOME |`intltool` |textproc/intltool |Ferramenta para Internacionalização (veja também intlhack) |`introspection` |devel/gobject-introspection |Ligações de introspecção e ferramentas básicas para gerar ligações de introspecção. Na maioria das vezes: build é suficiente, e :both/:run só é necessário para aplicativos que usam ligações de introspecção. (both, build, run) |`libgda5` |databases/libgda5 |Fornece acesso uniforme a diferentes tipos de fontes de dados |`libgda5-ui` |databases/libgda5-ui |Biblioteca de interface do usuário da biblioteca libgda5 |`libgdamm5` |databases/libgdamm5 |c++ bindings para a biblioteca libgda5 |`libgsf` |devel/libgsf |Abstração extensível de I/O para lidar com formatos de arquivo estruturados |`librsvg2` |graphics/librsvg2 |Biblioteca para analisar e renderizar arquivos gráficos vetoriais SVG |`libsigc++20` |devel/libsigc++20 |Framework de Callback para C++ |`libxml++26` |textproc/libxml++26 |c++ bindings para a biblioteca libxml2 |`libxml2` |textproc/libxml2 |Biblioteca do parser XML (both, build, run) |`libxslt` |textproc/libxslt |Biblioteca XSLT C (both, build, run) |`metacity` |x11-wm/metacity |Gerenciador de janelas do GNOME |`nautilus3` |x11-fm/nautilus |Gerenciador de arquivos GNOME |`pango` |x11-toolkits/cave |Estrutura de código aberto para o layout e renderização do texto i18n |`pangomm` |x11-toolkits/pangomm |c++ bindings para a biblioteca pango |`py3gobject3` |devel/py3-gobject3 |Python 3, GObject 3.0 bindings |`pygobject3` |devel/py-gobject3 |Python 2, GObject 3.0 bindings |`vte3` |x11-toolkits/vte3 |Widget de terminal com melhor acessibilidade e suporte I18N |=== [[gnome-components-macro]] .Componentes Macro do GNOME [cols="1,1", options="header"] |=== | Componente | Descrição |`gnomeprefix` |Forneça `configure` com alguns locais padrão. |`intlhack` |O mesmo que intltool, porém com os patches necessários para garantir o [.filename]#share/locale/#. Por favor, use somente quando `intltool` sozinho não for suficiente. |`referencehack` |Esta macro existe para ajudar a dividir a API ou a documentação de referência em seu próprio port. |=== [[gnome-components-legacy]] .Componentes Legados do GNOME [cols="1,1,1", options="header"] |=== | Componente | Programa associado | Descrição |`atspi` |accessibility/at-spi |Interface do Provedor de Serviços de Tecnologia Assistiva |`esound` |audio/esound |Pacote de som do Enlightenment |`gal2` |x11-toolkits/gal2 |Coleção de widgets obtidos do GNOME 2 gnumeric |`gconf2` |devel/gconf2 |Sistema de banco de dados de configuração para o GNOME 2 |`gconfmm26` |devel/gconfmm26 |c++ bindings para o gconf2 |`gdkpixbuf` |graphics/gdk-pixbuf |Biblioteca de gráficos para GTK+ |`glib12` |devel/glib12 |biblioteca principal glib 1.2 |`gnomedocutils` |textproc/gnome-doc-utils |Utilitários de documentação para o GNOME |`gnomemimedata` |misc/gnome-mime-data |MIME e banco de dados de aplicativos para o GNOME 2 |`gnomesharp20` |x11-toolkits/gnome-sharp20 |Interfaces do GNOME 2 para o tempo de execução do .NET |`gnomespeech` |accessibility/gnome-speech |API de conversão de texto em voz do GNOME 2 |`gnomevfs2` |devel/gnome-vfs |Sistema de Arquivos Virtual do GNOME 2 |`gtk12` |x11-toolkits/gtk12 |Kit de ferramentas Gtk+ 1.2 |`gtkhtml3` |www/gtkhtml3 |Mecanismo leve de renderização/impressão/edição de HTML |`gtkhtml4` |www/gtkhtml4 |Mecanismo leve de renderização/impressão/edição de HTML |`gtksharp20` |x11-toolkits/gtk-sharp20 |Interfaces GTK+ e GNOME 2 para o runtime .NET |`gtksourceview` |x11-toolkits/gtksourceview |Widget que adiciona destaque de sintaxe para o GtkTextView |`libartgpl2` |graphics/libart_lgpl |Biblioteca para gráficos 2D de alto desempenho |`libbonobo` |devel/libbonobo |Componente e sistema de documentos compostos para o GNOME 2 |`libbonoboui` |x11-toolkits/libbonoboui |GUI frontend para o componente libbonobo do GNOME 2 |`libgda4` |databases/libgda4 |Fornece acesso uniforme a diferentes tipos de fontes de dados |`libglade2` |devel/libglade2 |Biblioteca glade do GNOME 2 |`libgnome` |x11/libgnome |Bibliotecas para o GNOME 2, um ambiente de desktop GNU |`libgnomecanvas` |graphics/libgnomecanvas |Biblioteca Gráfica para o GNOME 2 |`libgnomekbd` |x11/libgnomekbd |Biblioteca compartilhada de teclado do GNOME 2 |`libgnomeprint` |print/libgnomeprint |Biblioteca de suporte de impressão do Gnome 2 |`libgnomeprintui` |x11-toolkits/libgnomeprintui |Biblioteca de suporte de impressão do Gnome 2 |`libgnomeui` |x11-toolkits/libgnomeui |Bibliotecas para a GUI do GNOME 2, um ambiente de desktop GNU |`libgtkhtml` |www/libgtkhtml |Mecanismo leve de renderização/impressão/edição de HTML |`libgtksourceviewmm` |x11-toolkits/libgtksourceviewmm |c++ binding do GtkSourceView |`libidl` |devel/libIDL |Biblioteca para criação de árvores de arquivo do CORBA IDL |`libsigc++12` |devel/libsigc++12 |Framework de Callback para C++ |`libwnck` |x11-toolkits/libwnck |Biblioteca usada para escrever pagers e listas de tarefas |`libwnck3` |x11-toolkits/libwnck3 |Biblioteca usada para escrever pagers e listas de tarefas |`orbit2` |devel/ORBit2 |CORBA ORB de alto desempenho com suporte para a linguagem C |`pygnome2` |x11-toolkits/py-gnome2 |Python bindings para GNOME 2 |`pygobject` |devel/py-gobject |Python 2, GObject 2.0 bindings |`pygtk2` |x11-toolkits/py-gtk2 |Conjunto de Python bindings para GTK+ |`pygtksourceview` |x11-toolkits/py-gtksourceview |Python bindings para GtkSourceView 2 |`vte` |x11-toolkits/vte |Widget de terminal com melhor acessibilidade e suporte I18N |=== [[gnome-components-deprecated]] .Componentes Obsoletos: Não Use [cols="1,1", options="header"] |=== | Componente | Descrição |`pangox-compat` |O pangox-compatfoi descontinuado e separado do pacote pango. |=== [[using-qt]] == Usando o Qt [NOTE] ==== -Para ports que fazem parte do Qt, veja <>. +Para ports que fazem parte do Qt, veja crossref:uses[uses-qt-dist,`qt-dist`]. ==== [[qt-common]] === Ports que requerem o Qt A coleção de ports fornece suporte para o Qt 5 com `USES+=qt:5`. Configure o `USE_QT` para a lista de componentes obrigatórios do Qt (bibliotecas, ferramentas, plugins). O framework Qt exporta um número de variáveis ​​que podem ser usadas por ports, algumas delas listadas abaixo: [[using-qt-variables]] .Variáveis ​​Fornecidas aos Ports Que Usam o Qt [cols="1,1", frame="none"] |=== |`QMAKE` |Caminho completo para o binário `qmake`. |`LRELEASE` |Caminho completo para utilitário `Irelease`. |`MOC` |Caminho completo para `moc`. |`RCC` |Caminho completo para `rcc`. |`UIC` |Caminho completo para `uic`. |`QT_INCDIR` |Diretório include Qt. |`QT_LIBDIR` |Caminho das bibliotecas Qt. |`QT_PLUGINDIR` |Caminho de plugins do Qt. |=== [[qt-components]] === Seleção de Componentes As dependências individuais das ferramentas e da biblioteca Qt devem ser especificadas em `USE_QT`. Todo componente pode ser sufixado com `_build` ou `_run`, o sufixo indica se a dependência no componente está no tempo de compilação ou no tempo de execução. Se um sufixo não for usado, a dependência do componente será tanto em tempo de compilação quanto em tempo de execução. Geralmente, os componentes da biblioteca são especificados como unsuffixed, os componentes das ferramentas são especificados com o sufixo `_build` e os componentes dos plugins são especificados com o sufixo `_run`. Os componentes mais comumente usados estão listados abaixo (todos os componentes disponíveis estão listados em `_USE_QT_ALL` e `_USE_QT5_ONLY` em [.filename]#/usr/ports/Mk/Uses/qt.mk#): [[using-qt-library-list]] .Componentes da Biblioteca Qt Disponíveis [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`3d` |Módulo Qt3D |`assistant` |Navegador de documentação do Qt 5 |`canvas3d` |Módulo Qt canvas3d |`charts` |Módulo de gráficos Qt 5 |`concurrent` |Módulo multi-threading Qt |`connectivity` |Módulo de conectividade Qt (Bluetooth/NFC) |`core` |Módulo não-gráfico do núcleo Qt |`datavis3d` |Módulo de visualização de dados 3D Qt 5 |`dbus` |Módulo de comunicação entre processos Qt D-Bus |`declarative` |Framework declarativo Qt para interfaces dinâmicas de usuário |`designer` |Designer gráfico de interface de usuário do Qt 5 |`diag` |Ferramenta para relatar informações de diagnóstico sobre o Qt e seu ambiente |`doc` |Documentação do Qt 5 |`examples` |Código-fonte dos exemplos do Qt 5 |`gamepad` |Módulo de Gamepad Qt 5 |`graphicaleffects` |Efeitos gráficos rápidos do Qt |`gui` |Módulo de interface gráfica do usuário do Qt |`help` |Módulo de integração de ajuda on-line do Qt |`l10n` |Mensagens localizadas do Qt |`linguist` |Ferramenta de tradução do Qt 5 |`location` |Módulo de localização do Qt |`multimedia` |Módulo de suporte de áudio, vídeo, rádio e câmera do Qt |`network` |Módulo de rede do Qt |`networkauth` |Módulo de autenticação de rede do Qt |`opengl` |Módulo de suporte OpenGL compatível com o Qt 5 |`paths` |Cliente de linha de comando para QStandardPaths |`phonon4` |Framework de multimídia do KDE |`pixeltool` |Lupa de tela do Qt 5 |`plugininfo` |Dumper de metadados do plugin Qt5 |`printsupport` |Módulo de suporte de impressão do Qt |`qdbus` |Interface de linha de comando do Qt para o D-Bus |`qdbusviewer` |Interface gráfica do Qt 5 para o D-Bus |`qdoc` |Gerador de documentação do Qt |`qdoc-data` |Arquivos de configuração do QDoc |`qev` |Ferramenta de introspecção de eventos Qt QWidget |`qmake` |Gerador de Makefile do Qt |`quickcontrols` |Conjunto de controles para construir interfaces completas no Qt Quick |`quickcontrols2` |Conjunto de controles para construir interfaces completas no Qt Quick |`remoteobjects` |Módulo SXCML Qt5 |`script` |Módulo de script compatível com Qt 4 |`scripttools` |Componentes adicionais do Qt Script |`scxml` |Módulo SXCML Qt5 |`sensors` |Módulo de sensores do Qt |`serialbus` |Funções do Qt para acessar sistemas de bus industriais |`serialport` |Funções do Qt para acessar portas seriais |`speech` |Recursos de acessibilidade para o Qt5 |`sql` |Módulo de integração a banco de dados SQL do Qt |`sql-ibase` |Plugin de banco de dados InterBase/Firebird do Qt |`sql-mysql` |Plugin de banco de dados MySQL do Qt |`sql-odbc` |Plugin Qt para conectividade Open Database |`sql-pgsql` |Plugin de banco de dados do PostgreSQL do Qt |`sql-sqlite2` |Plugin de banco de dados SQLite 2 do Qt |`sql-sqlite3` |Plugin de banco de dados SQLite 3 do Qt |`sql-tds` |Plugin de conectividade ao banco de dados TDS do Qt |`svg` |Módulo de suporte SVT do Qt |`testlib` |Módulo de teste unitário do Qt |`uiplugin` |Interface de plug-in do Qt widget personalizado para o Qt Designer |`uitools` |Módulo de suporte a formulários de interface de usuário do Qt Designer |`virtualkeyboard` |Módulo de teclado virtual do Qt 5 |`wayland` |Qt5 wrapper para o Wayland |`webchannel` |Biblioteca Qt 5 para integração de C++/QML com clientes HTML/js |`webengine` |Biblioteca Qt 5 para renderizar conteúdo da web |`webkit` |QtWebKit com uma base de código WebKit mais moderna |`websockets` |Implementação do protocolo WebSocket do Qt |`websockets-qml` |Implementação do protocolo WebSocket do Qt (QML bindings) |`webview` |Componente do Qt para exibir o conteúdo da web |`widgets` |Módulo de widgets C++ do Qt |`x11extras` |Recursos específicos da plataforma Qt para sistemas baseados em X11 |`xml` |Implementações SAX e DOM do Qt |`xmlpatterns` |Suporte do Qt para XPath, XQuery, XSLT e XML Schema |=== Para determinar as bibliotecas das quais um aplicativo depende, execute o `ldd` no executável principal após uma compilação bem sucedida. [[using-qt-tools-list]] .Componentes Disponíveis da Ferramenta Qt [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`buildtools` |Ferramentas de compilação (`moc`, `rcc`), necessária para quase todas as aplicações do Qt. |`linguisttools` |ferramentas de localização: `Irelease`, `lupdate` |`qmake` |Utilitário gerador/compilador de Makefile |=== [[using-qt-plugins-list]] .Componentes Disponíveis de Plugin Qt [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`imageformats` |plugins para formatos de imagem TGA, TIFF e MNG |=== [[qt5-components-example]] .Selecionando Componentes do Qt 5 [example] ==== Neste exemplo, o aplicativo portado usa a biblioteca de interface gráfica do usuário do Qt 5, a biblioteca principal do Qt 5, todas as ferramentas de geração de código do Qt 5 e o gerador de Makefile do Qt 5. Uma vez que a biblioteca `gui` implica na dependência da biblioteca principal, o `core` não precisa ser especificado. As ferramentas de geração de código do Qt 5 `moc`, `uic` e `rcc`, bem como o gerador de Makefile `qmake` são necessários apenas em tempo de compilação, assim eles são especificados com o sufixo `_build`: [.programlisting] .... USES= qt:5 USE_QT= gui buildtools_build qmake_build .... ==== [[using-qmake]] === Usando `qmake` Se o aplicativo fornecer um arquivo de projeto qmake ([.filename]#*.pro#), defina `USES=qmake` junto com `USE_QTx`. Observe que `USES=qmake` já implica uma dependência de compilação no qmake, portanto, o componente qmake pode ser omitido de `USE_QT`. Igual ao <>, o qmake suporta compilações out-of-source, que podem ser ativadas especificando o argumento `outsource` (ver<>) . [[using-qmake-arguments]] .Argumentos Possíveis para `USES= qmake` [cols="1,1", frame="none", options="header"] |=== | Variável | Descrição |`no_configure` |Não adicione o target configure. Isso é implícito pelo `HAS_CONFIGURE=yes` e `GNU_CONFIGURE=yes`. Isso é requerido quando a compilação apenas precisa do ambiente de setup do `USES= qmake`, e dessa forma, executa-se o `qmake` por si próprio. |`no_env` |Suprime modificações dos ambientes configure e make. É necessário somente quando `qmake` é usado para configurar o software e a compilação falha em entender a configuração do ambiente pelo `USES= qmake`. |`norecursive` |Não passe o argumento `-recursive` para o `qmake`. |`outsource` |Realiza uma compilação out-of-source. |=== [[using-qmake-variables]] .Variáveis ​​para Ports Que Usam o `qmake` [cols="1,1", frame="none", options="header"] |=== | Variável | Descrição |`QMAKE_ARGS` |Flags específicas do port qmake a serem passadas para o binario do `qmake`. |`QMAKE_ENV` |Variáveis ​​de ambiente a serem definidas para o binario `qmake`. O padrão é `${CONFIGURE_ENV}`. |`QMAKE_SOURCE_PATH` |Caminho para os arquivos de projeto do qmake ([.filename]#.pro#). O padrão é `${WRKSRC}` se uma compilação out-of-source for solicitada, caso contrário, deixe em branco. |=== Ao usar `USES= qmake`, estas configurações são implementadas: [.programlisting] .... CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ --with-qt-libraries=${QT_LIBDIR} \ --with-extra-libs=${LOCALBASE}/lib \ --with-extra-includes=${LOCALBASE}/include CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \ QMAKESPEC="${QMAKESPEC}" PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ QT_LIBDIR=${QT_LIBDIR_REL} \ QT_PLUGINDIR=${QT_PLUGINDIR_REL} .... Alguns scripts de configuração não suportam os argumentos acima. Para suprimir a modificação de `CONFIGURE_ENV` e `CONFIGURE_ARGS` defina `USES= qmake:no_env`. [[using-qmake-example]] .Exemplo `USES= qmake` [example] ==== Este trecho demonstra o uso do qmake para um port Qt 5: [.programlisting] .... USES= qmake:outsource qt:5 USE_QT= buildtools_build .... ==== Aplicações Qt são frequentemente escritas para serem multi-plataforma e muitas vezes o X11/Unix não é a plataforma em que são desenvolvidas, o que por sua vez leva a certas pontas soltas, como: * _Faltam caminhos de inclusão adicionais._ Muitos aplicativos vêm com suporte ao ícone da bandeja do sistema, mas não buscam inclusões e/ou bibliotecas nos diretórios do X11. Para adicionar diretórios aos includes e bibliotecas de pesquisa do `qmake` através da linha de comando, use: + [.programlisting] .... QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib .... * _Caminhos falsos de instalação._ Às vezes, dados como ícones ou arquivos .desktop são instalados por padrão em diretórios que não são verificados por aplicativos compatíveis com XDG. O package:editors/texmaker[] é um exemplo disso - veja [.filename]#patch-texmaker.pro# no diretório de [.filename]#arquivos# desse port para um modelo sobre como remediar isso diretamente no arquivo de projeto `qmake`. [[using-kde]] == Usando o KDE [[kde5-variables]] === Definições de Variáveis ​​do KDE Se a aplicação depender do KDE, defina `USES+=kde:5` e defina `USE_KDE` com a lista de componentes necessários. Sufixos `_build` e `_run` podem ser usados ​​para forçar o tipo de dependência de componentes (por exemplo, `baseapps_run`). Se nenhum sufixo for definido, o tipo padrão de dependência será usado. Para forçar os dois tipos, adicione o componente duas vezes com os dois sufixos (por exemplo, `ecm_build ecm_run`). Os componentes disponíveis estão listados abaixo (os componentes atualizados também estão listados em [.filename]#/usr/ports/Mk/Uses/kde.mk#): [[using-kde-components]] .Componentes Disponíveis do KDE [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`activities` |Biblioteca de tempo de execução do KF5 para organizar o trabalho em atividades separadas |`activities-stats` |Estatísticas do KF5 para atividades |`activitymanagerd` |Serviço do sistema para gerenciar atividades do usuário, rastrear os padrões de uso |`akonadi` |Servidor de armazenamento para o KDE-Pim |`akonadicalendar` |Integração de Calendário do Akonadi |`akonadiconsole` |Console de gerenciamento e depuração do Akonadi |`akonadicontacts` |Bibliotecas e daemons para implementar o gerenciamento de contatos do Akonadi |`akonadiimportwizard` |Importa dados de outros clientes de email para o KMail |`akonadimime` |Bibliotecas e daemons para implementar o tratamento básico de email |`akonadinotes` |Biblioteca do KDE para acessar caixas postais no formato MBox |`akonadisearch` |Bibliotecas e daemons para implementar buscas no Akonadi |`akregator` |Um leitor de feeds do KDE |`alarmcalendar` |API do KDE para alarmes do KAlarm |`apidox` |Ferramentas de Documentação da API KF5 |`archive` |Biblioteca KF5 que fornece classes para lidar com formatos de arquivo |`attica` |Biblioteca da API do Open Collaboration Services do KDE 5 |`attica5` |Biblioteca da API do Open Collaboration Services do KDE 5 |`auth` |Abstração do KF5 para funcionalidades de autenticação e políticas do sistema |`baloo` |KF5 Framework para pesquisar e gerenciar metadados do usuário |`baloo-widgets` |Biblioteca BalooWidgets |`baloo5` |KF5 Framework para pesquisar e gerenciar metadados do usuário |`blog` |API do KDE para acesso ao weblogging |`bookmarks` |Biblioteca KF5 para bookmarks e para o formato XBEL |`breeze` |Arte, estilos e recursos do Plasma5 para o estilo visual Breeze |`breeze-gtk` |Estilo visual do Plasma5 Breeze para Gtk |`breeze-icons` |Tema de ícones do Breeze para o KDE |`calendarcore` |Biblioteca de acesso ao calendário do KDE |`calendarsupport` |Bibliotecas de suporte de calendário para o KDEPim |`calendarutils` |Utilitário KDE e funções da interface do usuário para acessar o calendário |`codecs` |Biblioteca KF5 para manipulação de string |`completion` |Assistentes e widgets de conclusão de texto do KF5 |`config` |Widgets do KF5 para diálogos de configuração |`configwidgets` |Widgets do KF5 para diálogos de configuração |`contacts` |Api do KDE para gerenciar informações de contato |`coreaddons` |Complementos do KF5 para o QtCore |`crash` |Biblioteca KF5 para lidar com análise de falhas e relatório de erros de aplicativos |`dbusaddons` |Complementos do KF5 para o QtDBus |`decoration` |Biblioteca do Plasma5 para criar decorações de janelas |`designerplugin` |Integração do KF5 para widgets de Framework no Qt Designer/Creator |`discover` |Ferramentas de gerenciamento de pacotes do Plasma5 |`dnssd` |Abstração do KF5 para os recursos do sistema DNSSD |`doctools` |Geração de documentação do KF5 a partir do docbook |`drkonqi` |Manipulador de falhas do Plasma5 |`ecm` |Módulos e scripts extras para o CMake |`emoticons` |Biblioteca KF5 para converter emoticons |`eventviews` |Bibliotecas de visualização de eventos para o KDEPim |`filemetadata` |Biblioteca KF5 para extrair metadados de arquivos |`frameworkintegration` |Espaço de trabalho e plugins de integração entre estruturas KF5 |`gapi` |Biblioteca baseada no KDE para acessar serviços do Google |`globalaccel` |Biblioteca KF5 para incluir suporte para atalhos do espaço de trabalho global |`grantlee-editor` |Editor para os temas de Grantlee |`grantleetheme` |KDE PIM grantleetheme |`gravatar` |Biblioteca para suporte a gravatar |`guiaddons` |Complementos do KF5 para o QtGui |`holidays` |Biblioteca do KDE para feriados do calendário |`hotkeys` |Biblioteca do Plasma5 para teclas de atalho |`i18n` |Framework avançado de internacionalização do KF5 |`iconthemes` |Biblioteca KF5 para manipular ícones em aplicativos |`identitymanagement` |Identidades do KDE pim |`idletime` |Biblioteca KF5 para monitorar a atividade do usuário |`imap` |API do KDE para suporte a IMAP |`incidenceeditor` |Bibliotecas do editor de incidências para o KDE Pim |`infocenter` |Utilidade do Plasma5 fornecendo informações do sistema |`init` |Iniciador de processos KF5 para acelerar o lançamento de aplicativos do KDE |`itemmodels` |Modelos KF5 para o sistema Qt Model / View |`itemviews` |KF5 widget addons para Qt Model/View |`jobwidgets` |Widgets do KF5 para rastrear a instância do KJob |`js` |Biblioteca KF5 que fornece um interpretador de script ECMA |`jsembed` |Biblioteca KF5 para ligar objetos JavaScript a QObjects |`kaddressbook` |Gerenciador de contatos do KDE |`kalarm` |Agendador de alarmes pessoal |`kalarm` |Agendador de alarmes pessoal |`kate` |Framework básico do editor para o sistema KDE |`kcmutils` |Utilitários KF5 para trabalhar com KCModules |`kde-cli-tools` |Ferramentas não interativas do sistema do Plasma5 |`kde-gtk-config` |Configurador Plasma5 GTK2 e GTK3 |`kdeclarative` |Biblioteca KF5 que prove a integração dos frameworks do QML e do KDE |`kded` |Daemon extensível do KF5 para fornecer serviços a nível do sistema |`kdelibs4support` |KF5 porting aid from KDELibs4 |`kdepim-addons` |Complementos do KDE PIM |`kdepim-apps-libs` |Bibliotecas do KDE PIM relacionadas ao correio |`kdepim-runtime5` |Ferramentas e serviços do KDE PIM |`kdeplasma-addons` |Complementos do Plasma 5 para melhorar a experiência do Plasma |`kdesu` |Integração do KF5 com o su para privilégios elevados |`kdewebkit` |Biblioteca KF5 que fornece a integração do QtWebKit |`kgamma5` |Configurações de gama do monitor Plasma5 |`khtml` |Motor de renderização KF5 KTHML |`kimageformats` |Biblioteca KF5 que fornece suporte para formatos de imagem adicionais |`kio` |Recurso e abstração de acesso à rede do KF5 |`kirigami2` |Conjunto de componentes baseados em QtQuick |`kitinerary` |Modelo de dados e sistema de extração para informações de reservas de viagens |`kmail` |Cliente de correio do KDE |`kmail` |Cliente de correio do KDE |`kmail-account-wizard` |Assistente de conta de e-mail do KDE |`kmenuedit` |Editor de menu do Plasma5 |`knotes` |Notas pop-up |`kontact` |Gerenciador de Informações Pessoais do KDE |`kontact` |Gerenciador de Informações Pessoais do KDE |`kontactinterface` |Cola do KDE para incorporar KParts no Kontact |`korganizer` |Programa de calendário e agendamento |`kpimdav` |Uma implementação do protocolo DAV com KJobs |`kpkpass` |Biblioteca para lidar com pass files da Apple Wallet |`kross` |Aplicação de scripting multi-language do KF5 |`kscreen` |Biblioteca de gerenciamento de tela do Plasma5 |`kscreenlocker` |Arquitetura de tela de bloqueio seguro do Plasma5 |`ksmtp` |Biblioteca job-based para enviar email através de um servidor SMTP |`ksshaskpass` |Frontend ssh-add do Plasma5 |`ksysguard` |Utilitário Plasma5 para rastrear e controlar os processos em execução |`kwallet-pam` |Integração PAM do Plasma5 KWallet |`kwayland-integration` |Plugins de integração para um desktop baseado em Wayland |`kwin` |Gerenciador de janelas do Plasma5 |`kwrited` |Daemon do Plasma5 para ouvir paredes e escrever mensagens |`ldap` |API de acesso LDAP para o KDE |`libkcddb` |Biblioteca KDE CDDB |`libkcompactdisc` |Biblioteca do KDE para interfaceamento com CDs de áudio |`libkdcraw` |Interface LibRaw para o KDE |`libkdegames` |Bibliotecas usadas pelos jogos do KDE |`libkdepim` |Bibliotecas KDE PIM |`libkeduvocdocument` |Biblioteca para leitura e gravação de arquivos de vocabulário |`libkexiv2` |Interface da biblioteca Exiv2 para o KDE |`libkipi` |Interface de Plugin de Imagem do KDE |`libkleo` |Gerenciador de certificados para o KDE |`libksane` |Interface da biblioteca SANE para o KDE |`libkscreen` |Biblioteca de gerenciamento de tela do Plasma5 |`libksieve` |Bibliotecas de inspeção para o KDEPim |`libksysguard` |Biblioteca do Plasma5 para rastrear e controlar processos em execução |`mailcommon` |Bibliotecas comuns para o KDEPim |`mailimporter` |Importar arquivos mbox para o KMail |`mailtransport` |Biblioteca do KDE para gerenciar o transporte de correio |`marble` |Globo virtual e atlas mundial para o KDE |`mbox` |Biblioteca do KDE para acessar caixas postais no formato MBox |`mbox-importer` |Importar arquivos mbox para o KMail |`mediaplayer` |Interface de plug-in do KF5 para recursos do media player |`messagelib` |Biblioteca para manipular mensagens |`milou` |Plasma5 Plasmóide para pesquisa |`mime` |Biblioteca para manipular dados MIME |`newstuff` |Biblioteca KF5 para baixar aplicativos da rede |`notifications` |Abstração KF5 para notificações do sistema |`notifyconfig` |Sistema de configuração KF5 para o KNotify |`okular` |Visualizador universal de documentos do KDE |`oxygen` |Estilo Oxygen Plasma5 |`oxygen-icons5` |O tema de ícones do Oxygen para o KDE |`package` |Biblioteca KF5 para carregar e instalar pacotes |`parts` |Sistema de plugin centrado em documentos KF5 |`people` |Biblioteca KF5 para fornecer acesso a contatos |`pim-data-exporter` |Importar e exportar configurações do KDE PIM |`pimcommon` |Bibliotecas comuns para o KDEPim |`pimtextedit` |Biblioteca do KDE para utilitários de edição de texto específicos do PIM |`plasma-browser-integration` |Componentes do Plasma5 para integrar navegadores na área de trabalho |`plasma-desktop` |Área de trabalho plasma Plasma5 |`plasma-framework` |UI runtime baseado no plugin KF5 usado para escrever interfaces de usuários |`plasma-integration` |Plugins de integração do Qt Platform Theme para os workspaces do Plasma |`plasma-pa` |Misturador de áudio de pulso do Plasma5 Plasma |`plasma-sdk` |Aplicações do Plasma5 úteis para o desenvolvimento Plasma |`plasma-workspace` |Workspace Plasma5 Plasma |`plasma-workspace-wallpapers` |Plasma5 wallpapers |`plotting` |Framework de plotagem leve KF5 |`polkit-kde-agent-1` |Daemon do Plasma5 que fornece uma interface de usuário de autenticação do polkit |`powerdevil` |Ferramenta Plasma5 para gerenciar as configurações de consumo de energia |`prison` |API para produzir códigos de barras |`pty` |Abstração KF5 pty |`purpose` |Oferece ações disponíveis para um propósito específico |`qqc2-desktop-style` |Estilo Qt QuickControl2 para o KDE |`runner` |Sistema de consulta paralelizado do KF5 |`service` |Plugin KF5 avançado e serviço de introspecção |`solid` |Integração e detecção de hardware do KF5 |`sonnet` |Biblioteca de verificação de ortografia baseada no plugin do KF5 |`syndication` |Biblioteca de manipulação de feeds do KDE |`syntaxhighlighting` |Mecanismo de destaque de sintaxe KF5 para texto e código estruturados |`systemsettings` |Configurações do sistema Plasma5 |`texteditor` |Editor avançado de texto embutido do KF5 |`textwidgets` |Widgets avançados do KF5 para edição de texto |`threadweaver` |Complementos do KF5 para o QtDBus |`tnef` |API do KDE para o tratamento de dados TNEF |`unitconversion` |Biblioteca KF5 para conversão de unidade |`user-manager` |Gerenciador de usuários do Plasma5 |`wallet` |Contêiner KF5 seguro e unificado para senhas de usuários |`wayland` |Wrapper da biblioteca KF5 Cliente e Servidor para as bibliotecas Wayland |`widgetsaddons` |Complementos do KF5 para o QtWidgets |`windowsystem` |Biblioteca KF5 para acesso ao sistema de janelas |`xmlgui` |Janelas principais configuráveis pelo usuário do KF5 |`xmlrpcclient` |Interação KF5 com serviços XMLRPC |=== [[kde5-components-example]] .Exemplo `USE_KDE` [example] ==== Este é um exemplo simples para um port do KDE. O `USES= cmake` instrui o port a utilizar o CMake, uma ferramenta de configuração amplamente usada pelos projetos do KDE (veja <>para informações detalhadas sobre o uso). O `USE_KDE` informa a dependência das bibliotecas do KDE. Os componentes necessários do KDE e outras dependências podem ser determinadas através do log de configuração. O `USE_KDE` não implica no `USE_QT`. Se um port requer alguns componentes do Qt, especifique-os em `USE_QT`. [.programlisting] .... USES= cmake kde:5 qt:5 USE_KDE= ecm USE_QT= core buildtools_build qmake_build .... ==== [[using-lxqt]] == Usando o LXQt As aplicações que dependem do LXQt devem definir `USES+= lxqt` e definir a variável `USE_LXQT` para a lista de componentes necessários da tabela abaixo [[using-lxqt-components]] .Componentes disponíveis do LXQt [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`buildtools` |Auxiliares para módulos CMake adicionais |`libfmqt` |Libfm Qt bindings |`lxqt` |LXQt core library |`qtxdg` |Implementação do Qt das especificações do XDG do freedesktop.org |=== [[lxqt-components-example]] .Exemplo `USE_LXQT` [example] ==== Este é um exemplo simples, `USE_LXQT` adiciona uma dependência em bibliotecas LXQt. Os componentes necessários do LXQt e outras dependências podem ser determinados a partir do log de configuração. [.programlisting] .... USES= cmake lxqt qt:5 tar:xz USE_QT= core dbus widgets buildtools_build qmake_build USE_LXQT= buildtools libfmqt .... ==== [[using-java]] == Usando Java [[java-variables]] === Definições de Variáveis Se o port precisar de um Java(TM) Development Kit (JDK) para compilar, executar ou até mesmo extrair o distfile, então defina `USE_JAVA`. Existem vários JDKs na coleção de ports, de vários fornecedores e em várias versões. Se o port precisar usar uma versão específica, especifique-a usando a variável `JAVA_VERSION`. A versão mais atual é package:java/openjdk15[], com package:java/openjdk14[], package:java/openjdk13[], package:java/openjdk12[], package:java/openjdk11[], package:java/openjdk8[], e package:java/openjdk7[] também disponíveis. [[using-java-variables]] .Variáveis ​​Que Podem ser Definidas por Ports Que Usam Java [cols="1,1", frame="none", options="header"] |=== | Variável | Significa |`USE_JAVA` |Defina para as variáveis ​​restantes para ter algum efeito. |`JAVA_VERSION` |Lista das versões Java adequadas separadas por espaço para o port. Um opcional `"+"` permite especificar um intervalo de versões (valores permitidos: `7[+] 8[+] 11[+] 12[+] 13[+] 14[+] 15[+]`). |`JAVA_OS` |Lista de sistemas operacionais adequados do port JDK separados por espaço para o port (valores permitidos: `native linux`). |`JAVA_VENDOR` |Lista de fornecedores adequados de ports JDK separados por espaços para o port (valores permitidos: `freebsd bsdjava sun openjdk`). |`JAVA_BUILD` |Quando definido, adiciona o port JDK selecionado às dependências de compilação. |`JAVA_RUN` |Quando definido, adicione o port JDK selecionado às dependências de execução. |`JAVA_EXTRACT` |Quando definido, adicione o port JDK selecionado às dependências de extração. |=== Abaixo está a lista de todas as configurações que um port receberá após a configuração de `USE_JAVA`: [[using-java-variables2]] .Variáveis ​​Fornecidas para Ports que Usam Java [cols="1,1", frame="none", options="header"] |=== | Variável | Valor |`JAVA_PORT` |O nome do port do JDK (por exemplo,`java/openjdk6`). |`JAVA_PORT_VERSION` |A versão completa do port do JDK (por exemplo,`1.6.0`). Somente os dois primeiros dígitos deste número de versão são necessários, use `${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}`. |`JAVA_PORT_OS` |O sistema operacional usado pelo port do JDK (por exemplo, `'native'`). |`JAVA_PORT_VENDOR` |O fornecedor do port JDK (por exemplo,`'openjdk'`). |`JAVA_PORT_OS_DESCRIPTION` |Descrição do sistema operacional usado pelo port JDK (por exemplo, `'Native'`). |`JAVA_PORT_VENDOR_DESCRIPTION` |Descrição do fornecedor do port JDK (por exemplo,`'OpenJDK BSD Porting Team'`). |`JAVA_HOME` |Caminho para o diretório de instalação do JDK (por exemplo, [.filename]#'/usr/local/openjdk6'#). |`JAVAC` |Caminho para o compilador Java (por exemplo, [.filename]#'/usr/local/openjdk6/bin/javac'#). |`JAR` |Caminho para ferramenta `jar` a ser usada (por exemplo, [.filename]#'/usr/local/openjdk6/bin/jar'# ou [.filename]#'/usr/local/bin/fastjar'#). |`APPLETVIEWER` |Caminho para o utilitário `appletviewer` (por exemplo,[.filename]#'/usr/local/openjdk6/bin/appletviewer'#). |`JAVA` |Caminho para o executável `Java`. Use isto para executar programas Java (por exemplo, [.filename]#'/usr/local/openjdk6/bin/java'#). |`JAVADOC` |Caminho para o utilitário `javadoc`. |`JAVAH` |Caminho para o programa `javah`. |`JAVAP` |Caminho para o programa `javap`. |`JAVA_KEYTOOL` |Caminho para o utilitário `keytool`. |`JAVA_N2A` |Caminho para a ferramenta `native2ascii`. |`JAVA_POLICYTOOL` |Caminho para o programa `policytool`. |`JAVA_SERIALVER` |Caminho para o utilitário `serialver`. |`RMIC` |Caminho para o gerador de stub/skeleton RMI, `rmic`. |`RMIREGISTRY` |Caminho para o programa de registro RMI, `rmiregistry`. |`RMID` |Caminho para o daemon do RMI `rmid`. |`JAVA_CLASSES` |Caminho para o arquivo que contém os arquivos de classe do JDK, [.filename]#${JAVA_HOME}/jre/lib/rt.jar#. |=== Use o `java-debug` make target para obter informações para depurar o port. Ele exibirá o valor de muitas das variáveis ​​listadas anteriormente. Além disso, essas constantes são definidas para que todos os ports Java possam ser instalados de maneira consistente: [[using-java-constants]] .Constantes definidas para os ports que usam Java [cols="1,1", frame="none", options="header"] |=== | Constante | Valor |`JAVASHAREDIR` |O diretório base para tudo relacionado ao Java. Padrão: [.filename]#${PREFIX}/shared/java#. |`JAVAJARDIR` |O diretório onde os arquivos JAR são instalados. Padrão: [.filename]#${JAVASHAREDIR}/classes#. |`JAVALIBDIR` |O diretório onde os arquivos JAR instalados por outros ports estão localizados. Padrão: [.filename]#${LOCALBASE}/shared/java/classes#. |=== -As entradas relacionadas são definidas em ambos `PLIST_SUB` (documentado em <>) e `SUB_LIST`. +As entradas relacionadas são definidas em ambos `PLIST_SUB` (documentado em crossref:plist[plist-sub,Alterando o pkg-plist Baseado em Variáveis Make]) e `SUB_LIST`. [[java-building-with-ant]] === Compilando com Ant Quando o port deve ser compilado usando o Apache Ant, ele deve definir `USE_ANT`. Ant é, portanto, considerado o comando sub-make. Quando nenhum target `do-build` é definido pelo port, será definido um padrão que execute Ant de acordo com `MAKE_ENV`, `MAKE_ARGS` e `ALL_TARGET`. Isso é semelhante ao mecanismo `USES=gmake`, documentado em <>. [[java-best-practices]] === Melhores Práticas Ao portar uma biblioteca Java, o port precisa instalar o(s) arquivo(s) JAR em [.filename]#${JAVAJARDIR}# e o resto em [.filename]#${JAVASHAREDIR}/${PORTNAME}# (exceto para a documentação, veja abaixo). Para reduzir o tamanho do arquivo de empacotamento, faça referência aos arquivos JAR diretamente no [.filename]#Makefile#. Use esta declaração (onde [.filename]#myport.jar# é o nome do arquivo JAR instalado como parte do port): [.programlisting] .... PLIST_FILES+= ${JAVAJARDIR}/myport.jar .... Ao portar um aplicativo Java, o port geralmente instala tudo em um único diretório (incluindo suas dependências JAR). O uso de [.filename]#${JAVASHAREDIR}/${PORTNAME}# é fortemente indicado neste caso. Cabe ao mantenedor do port decidir se o port instala as dependências JAR adicionais sob esse diretório ou utiliza as já instaladas (de [.filename]#${JAVAJARDIR}#). Ao portar um aplicativo Java(TM) que requer um servidor de aplicação, como o package:www/tomcat7[] para executar o serviço, é bastante comum que o fornecedor distribua um [.filename]#.war#. Um [.filename]#.war# é uma aplicação Web ARchive a qual é extraído quando chamado pelo aplicativo. Evite adicionar um [.filename]#.war# no [.filename]#pkg-plist#. Isto não é considerado a melhor prática. Um servidor de aplicação irá expandir o arquivo war mas não irá remove-lo se o port for desinstalado. Uma forma mais desejável de trabalhar com este arquivo é extrair o seu conteudo, depois instalar os arquivos e, por fim, adicionar esses arquivos ao [.filename]#pkg-plist#. [.programlisting] .... TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 WEBAPPDIR= myapplication post-extract: @${MKDIR} ${WRKDIR}/${PORTDIRNAME} @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} do-install: cd ${WRKDIR} && \ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME} .... Independentemente do tipo de port (biblioteca ou aplicativo), a documentação adicional é instalada na <> como para qualquer outro port. A ferramenta Javadoc é conhecida por produzir um conjunto diferente de arquivos, dependendo da versão do JDK utilizado. Para ports que não impõem o uso de um determinado JDK, é uma tarefa complexa especificar a lista de empacotamento ([.filename]#pkg-plist#). Esta é uma razão pela qual os mantenedores de ports são fortemente encorajados a usar `PORTDOCS`. Além disso, mesmo se o conjunto de arquivos que serão gerados pelo `javadoc` puder ser previsto, o tamanho do [.filename]#pkg-plist# resultante irá encorajar o uso do `PORTDOCS`. -O valor padrão para `DATADIR` é [.filename]#${PREFIX}/shared/${PORTNAME}#. É uma boa ideia sobreescrever `DATADIR` para [.filename]#${JAVASHAREDIR}/${PORTNAME}# para ports Java. De fato, `DATADIR` é automaticamente adicionado a `PLIST_SUB` (documentado em<>) então use `%%DATADIR%%` diretamente em [.filename]#pkg-plist#. +O valor padrão para `DATADIR` é [.filename]#${PREFIX}/shared/${PORTNAME}#. É uma boa ideia sobreescrever `DATADIR` para [.filename]#${JAVASHAREDIR}/${PORTNAME}# para ports Java. De fato, `DATADIR` é automaticamente adicionado a `PLIST_SUB` (documentado em crossref:plist[plist-sub, Alterando o pkg-plist Baseado em Variáveis Make]) então use `%%DATADIR%%` diretamente em [.filename]#pkg-plist#. Quanto à escolha de compilar ports Java a partir do código fonte ou instalar diretamente a partir de uma distribuição binária, não há política definida no momento da escrita deste livro. No entanto, os membros do https://www.freebsd.org/java/[Projeto Java do FreeBSD] encorajam os mantenedores de ports a terem seus ports compilados a partir do código fonte sempre que for possível. Todos os recursos que foram apresentados nesta seção são implementados em [.filename]#bsd.java.mk#. Se o port precisar de suporte Java mais sofisticado, por favor, primeiro dê uma olhada no log do http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log[bsd.java.mk no Subversion] pois normalmente leva algum tempo para documentar os recursos mais recentes. Então, se o suporte necessário que estiver faltando for benéfico para muitos outros ports Java, sinta-se à vontade para discuti-lo na http://lists.FreeBSD.org/mailman/listinfo/freebsd-java[Lista de discussão do FreeBSD sobre Linguagem Java]. Embora haja uma categoria `Java` para PRs, isso refere-se ao esforço de portabilidade do JDK do projeto Java do FreeBSD. Portanto, envie o port Java na categoria `ports` como para qualquer outro port, a menos que o problema esteja relacionado a uma implementação do JDK ou ao [.filename]#bsd.java.mk#. -Da mesma forma, existe uma política definida sobre as `CATEGORIAS` de um port Java, que é detalhada em <>. +Da mesma forma, existe uma política definida sobre as `CATEGORIAS` de um port Java, que é detalhada em crossref:makefiles[makefile-categories,Categorização]. [[using-php]] == Aplicações Web, Apache e PHP [[using-apache]] === Apache [[using-apache-variables]] .Variáveis ​​para Ports Que Usam o Apache [cols="1,1", frame="none"] |=== |`USE_APACHE` |O port requer o Apache. Valores possíveis: `yes` (obtém qualquer versão), `22`, `24`, `22 a 24`, `22+`, etc. A versão padrão do APACHE é `22`. Mais detalhes estão disponíveis em [.filename]#ports/Mk/bsd.apache.mk# e em https://wiki.freebsd.org/Apache/[wiki.freebsd.org/Apache/]. |`APXS` |Caminho completo para o binário `apxs`. Pode ser modificado no port. |`HTTPD` |Caminho completo para o binário `httpd`. Pode ser modificado no port. |`APACHE_VERSION` |A versão da instalação atual do Apache (variável somente leitura). Esta variável só está disponível após a inclusão de [.filename]#bsd.port.pre.mk#. Valores possíveis: `22`, `24`. |`APACHEMODDIR` |Diretório para módulos Apache. Esta variável é automaticamente expandida em [.filename]#pkg-plist#. |`APACHEINCLUDEDIR` |Diretório para cabeçalhos Apache. Esta variável é automaticamente expandida em [.filename]#pkg-plist#. |`APACHEETCDIR` |Diretório para arquivos de configuração do Apache. Esta variável é automaticamente expandida em [.filename]#pkg-plist#. |=== [[using-apache-modules]] .Variáveis ​​Úteis para Portar Módulos do Apache [cols="1,1", frame="none"] |=== |`MODULENAME` |Nome do módulo. O valor padrão é `PORTNAME`. Exemplo: `mod_hello` |`SHORTMODNAME` |Nome abreviado do módulo. Automaticamente derivado de `MODULENAME`, mas pode ser substituído. Exemplo: `hello` |`AP_FAST_BUILD` |Use o `apxs` para compilar e instalar o módulo. |`AP_GENPLIST` |Também cria automaticamente um [.filename]#pkg-plist#. |`AP_INC` |Adiciona um diretório ao caminho de pesquisa de cabeçalhos durante a compilação. |`AP_LIB` |Adiciona um diretório ao caminho de pesquisa de bibliotecas durante a compilação. |`AP_EXTRAS` |Flags adicionais para passar para o `apxs`. |=== [[web-apps]] === Aplicações Web Aplicações web devem ser instaladas em [.filename]#PREFIX/www/appname#. Este caminho está disponível tanto no [.filename]#Makefile# quanto no [.filename]#pkg-plist# como `WWWDIR` e o caminho relativo para `PREFIX` está disponível no [.filename]#Makefile# como `WWWDIR_REL`. O usuário e o grupo do processo do servidor web estão disponíveis como `WWWOWN` e `WWWGRP`, no caso de a propriedade de alguns arquivos precisar ser alterada. Os valores padrão de ambos são `www`. Use `WWWOWN?=myuser` e `WWWGRP?=mygroup` se o port precisar de valores diferentes. Isso permite ao usuário substituí-los facilmente. [IMPORTANT] ==== Use `WWWOWN` e `WWWGRP` com moderação. Lembre-se de que todos os arquivos para os quais o servidor web tem permissão de escrita, são um risco de segurança esperando para acontecer. ==== Não insira o Apache como dependência, a menos que o aplicativo web precise explicitamente do Apache. Respeite que os usuários podem desejar executar um aplicativo web em um servidor web diferente do Apache. [[php-variables]] === PHP -Aplicações PHP declaram sua dependência a ele com `USES=php`. Veja <> para maiores informações. +Aplicações PHP declaram sua dependência a ele com `USES=php`. Veja crossref:uses[uses-php,`php`] para maiores informações. [[php-pear]] === Módulos PEAR Portar módulos PEAR é um processo muito simples. Adicione `USES=pear` ao [.filename]#Makefile# do port. O framework instalará os arquivos relevantes nos lugares certos e gerará automaticamente a lista no momento da instalação. [[pear-makefile]] .Exemplo de Makefile para Classes PEAR [example] ==== [.programlisting] .... PORTNAME= Date DISTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= example@domain.com COMMENT= PEAR Date and Time Zone Classes USES= pear .include .... ==== [TIP] ==== Os módulos PEAR serão automaticamente flavorizados usando <>. ==== [NOTE] ==== Se um `PEAR_CHANNEL` não padrão for usado, as dependências de compilação e de tempo de execução serão automaticamente adicionadas. ==== [IMPORTANT] ==== Módulos PEAR não precisam definir `PKGNAMESUFFIX`, é preenchido automaticamente usando `PEAR_PKGNAMEPREFIX`. Se um port precisar adicionar `PKGNAMEPREFIX`, também deve usar `PEAR_PKGNAMEPREFIX` para diferenciar entre diferentes flavors. ==== [[php-horde]] ==== Módulos Horde Da mesma forma, portar módulos Horde é um processo simples. Adicione `USES=horde` ao [.filename]#Makefile# do port . O framework instalará os arquivos relevantes nos lugares certos e gerará automaticamente a lista no momento da instalação. As variáveis `USE_HORDE_BUILD` e `USE_HORDE_RUN` podem ser usadas para adicionar dependências de tempo de compilação e de tempo de execução em outros módulos Horde. Veja [.filename]#Mk/Uses/horde.mk# para uma lista completa dos módulos disponíveis. [[horde-Makefile]] .Exemplo de Makefile para Módulos Horde [example] ==== [.programlisting] .... PORTNAME= Horde_Core DISTVERSION= 2.14.0 CATEGORIES= devel www pear MAINTAINER= horde@FreeBSD.org COMMENT= Horde Core Framework libraries OPTIONS_DEFINE= KOLAB SOCKETS KOLAB_DESC= Enable Kolab server support SOCKETS_DESC= Depend on sockets PHP extension USES= horde USE_PHP= session USE_HORDE_BUILD= Horde_Role USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \ Horde_Text_Filter Horde_View KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session SOCKETS_USE= PHP=sockets .include .... ==== [TIP] ==== Como os módulos Horde também são módulos PEAR, eles também serão automaticamente aromatizados usando <>. ==== [[using-python]] == Usando Python A Coleção de Ports suporta a instalação paralela de várias versões do Python. Os ports devem usar um interpretador `python`, de acordo com a configuração do usuário de `PYTHON_VERSION`. Mais proeminentemente, isso significa substituir o caminho para o executável `python` em scripts com o valor de `PYTHON_CMD`. Ports que instalam arquivos sob `PYTHON_SITELIBDIR` devem usar o prefixo `pyXY-` no prefixo do nome do pacote, assim o nome do pacote irá incorporar a versão do Python em que estão instalados. [.programlisting] .... PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} .... [[using-python-variables]] .Variáveis úteis para Ports que usam Python [cols="1,1", frame="none"] |=== |`USES=python` |O port precisa do Python. A versão mínima necessária pode ser especificada com valores como `2.7+`. Os intervalos de versão também podem ser especificados separando dois números de versão com um traço: `USES=python:3.2-3.3` |`USE_PYTHON=distutils` |Use o distutils do Python para configurar, compilar e instalar. Isso é necessário quando o port vem com [.filename]#setup.py#. Isso sobrescreve os targets `do-build` e `do-install` e também pode substituir `do-configure` se o `GNU_CONFIGURE` não estiver definido. Além disso, isso implica em `USE_PYTHON=flavors`. |`USE_PYTHON=autoplist` |Crie a lista de empacotamento automaticamente. Isso também requer que `USE_PYTHON=distutils` seja definido. |`USE_PYTHON=concurrent` |O port usará um prefixo exclusivo, normalmente `PYTHON_PKGNAMEPREFIX` para determinados diretórios, como `EXAMPLESDIR` e `DOCSDIR` e também irá acrescentar um sufixo, a versão python de `PYTHON_VER`, para os binários e scripts que serão instalados. Isso permite que os ports sejam instalados para diferentes versões do Python ao mesmo tempo, o que de outra forma instalaria arquivos conflitantes. |`USE_PYTHON=flavors` -|O port não usa distutils, mas ainda suporta várias versões do Python. .`FLAVORS` será definido para as versões suportadas do Python. Veja <> para maiores informações. +|O port não usa distutils, mas ainda suporta várias versões do Python. .`FLAVORS` será definido para as versões suportadas do Python. Veja crossref:flavors[flavors-auto-python,`USES`=python e Flavors] para maiores informações. |`USE_PYTHON=optsuffix` |Se a versão atual do Python não for a versão padrão, o port receberá `PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}`. É útil apenas com flavors. |`PYTHON_PKGNAMEPREFIX` |Usado como um `PKGNAMEPREFIX` para distinguir pacotes para diferentes versões do Python. Exemplo: `py27-` |`PYTHON_SITELIBDIR` |Local da árvore site-packages, que contém o caminho de instalação do Python (geralmente `LOCALBASE`). A `PYTHON_SITELIBDIR` pode ser muito útil ao instalar módulos Python. |`PYTHONPREFIX_SITELIBDIR` |A variante PREFIX-clean do PYTHON_SITELIBDIR. Sempre use `%%PYTHON_SITELIBDIR%%` no [.filename]#pkg-plist# quando possível. O valor padrão de `%%PYTHON_SITELIBDIR%%` é `lib/python%%PYTHON_VERSION%%/site-packages` |`PYTHON_CMD` |Linha de comando do interpretador Python, incluindo o número da versão. |=== [[using-python-variables-helpers]] .Assistentes do Módulo de Dependências do Python [cols="1,1", frame="none"] |=== |`PYNUMERIC` |Linha de dependência para extensão numérica. |`PYNUMPY` |Linha de dependência para a nova extensão numérica, numpy. (PYNUMERIC foi descontinuado pelo fornecedor upstream). |`PYXML` |Linha de dependência para a extensão XML (não é necessária para o Python 2.0 e superior, pois também está na distribuição base). |`PY_ENUM34` |Dependência condicional do package:devel/py-enum34[] dependendo da versão do Python. |`PY_ENUM_COMPAT` |Dependência condicional do package:devel/py-enum-compat[] dependendo da versão do Python. |`PY_PATHLIB` |Dependência condicional do package:devel/py-pathlib[] dependendo da versão do Python. |`PY_IPADDRESS` |Dependência condicional do package:net/py-ipaddress[] dependendo da versão do Python. |`PY_FUTURES` |Dependência condicional do package:devel/py-futures[] dependendo da versão do Python. |=== Uma lista completa das variáveis disponíveis pode ser encontrada em [.filename]#/usr/ports/Mk/Uses/python.mk#. [IMPORTANT] ==== Todas as dependências para ports Python usando <> (quer com `USE_PYTHON=distutils` ou `USE_PYTHON=flavors`) deve ter o flavor Python anexado à sua origem usando `@${PY_FLAVOR}`. Veja <>. ==== [[python-Makefile]] .Makefile para um Módulo Python Simples [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= devel MAINTAINER= john@doe.tld COMMENT= Python sample module RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} USES= python USE_PYTHON= autoplist distutils .include .... ==== Algumas aplicações Python afirmam ter suporte a `DESTDIR` (que seria necessário para fazer o staging), mas ele está quebrado (Mailman até a versão 2.1.16, por exemplo). Isso pode ser contornado, recompilando os scripts. Isso pode ser feito, por exemplo, no target `post-build`. Assumindo que os scripts Python devem estar em `PYTHONPREFIX_SITELIBDIR` após a instalação, esta solução pode ser aplicada: [.programlisting] .... (cd ${STAGEDIR}${PREFIX} \ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;}) .... Isso recompila os fontes com um caminho relativo ao diretório de stage e acrescenta o valor de `PREFIX` para o nome do arquivo gravado no arquivo bytecode de saída por `-d`. O `-f` é necessário para forçar a recompilação e o `:S;${PREFIX}/;;` remove prefixos do valor de `PYTHONPREFIX_SITELIBDIR` para torná-lo relativo ao `PREFIX`. [[using-tcl]] == Usando Tcl/Tk A Coleção de Ports suporta a instalação paralela de múltiplas versões do Tcl/Tk. Ports devem tentar suportar pelo menos a versão padrão do Tcl/Tk e superior com `USES=tcl`. É possível especificar a versão desejada do `tcl` anexando `:xx`, por exemplo, `USES=tcl:85`. [[using-tcl-variables]] .As variáveis read only muito úteis para Ports que usam Tcl/Tk [cols="1,1", frame="none"] |=== |`TCL_VER` |versão major.minor escolhida do Tcl |`TCLSH` |caminho completo do interpretador Tcl |`TCL_LIBDIR` |caminho das bibliotecas Tcl |`TCL_INCLUDEDIR` |caminho dos arquivos de cabeçalho C do Tcl |`TK_VER` |versão major.minor escolhida do Tk |`WISH` |caminho completo do interpretador Tk |`TK_LIBDIR` |caminho das bibliotecas Tk |`TK_INCLUDEDIR` |caminho dos arquivos de cabeçalho C do Tk |=== -Veja o <> e <> do <> para uma descrição completa dessas variáveis. Uma lista completa dessas variáveis ​​está disponível em [.filename]#/usr/ports/Mk/Uses/tcl.mk#. +Veja o <> e <> do crossref:uses[uses,Usando Macros `USES`] para uma descrição completa dessas variáveis. Uma lista completa dessas variáveis ​​está disponível em [.filename]#/usr/ports/Mk/Uses/tcl.mk#. [[using-ruby]] == Usando Ruby [[using-ruby-variables]] .Variáveis ​​Úteis para Ports Que Usam Ruby [cols="1,1", frame="none", options="header"] |=== | Variável | Descrição |`USE_RUBY` |Adiciona dependências de build e run no Ruby. |`USE_RUBY_EXTCONF` |O port utiliza [.filename]#extconf.rb# para configurar. |`USE_RUBY_SETUP` |O port utiliza [.filename]#setup.rb# para configurar. |`RUBY_SETUP` |Substitui o nome do script de configuração do [.filename]#setup.rb#. Outro valor comum é [.filename]#install.rb#. |=== Esta tabela mostra as variáveis selecionadas disponíveis para os autores dos ports através da infraestrutura de ports. Essas variáveis são usadas para instalar arquivos em seus locais apropriados. Use-os em [.filename]#pkg-plist# tanto quanto possível. Não redefina essas variáveis no port. [[using-ruby-variables-ro]] .Variáveis ​​Somente Leitura Selecionadas para Ports Que Usam Ruby [cols="1,1,1", frame="none", options="header"] |=== | Variável | Descrição | Exemplo de valor |`RUBY_PKGNAMEPREFIX` |Usado como um `PKGNAMEPREFIX` para distinguir pacotes para diferentes versões do Ruby. |`ruby19-` |`RUBY_VERSION` |Versão completa do Ruby na forma de `x.y.z[.p]`. |`1.9.3.484` |`RUBY_SITELIBDIR` |Caminho de instalação de bibliotecas independentes de arquitetura. |`/usr/local/lib/ruby/site_ruby/1.9` |`RUBY_SITEARCHLIBDIR` |Caminho de instalação das bibliotecas dependentes de arquitetura. |`/usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10` |`RUBY_MODDOCDIR` |Caminho de instalação da documentação do módulo. |`/usr/local/shared/doc/ruby19/patsy` |`RUBY_MODEXAMPLESDIR` |Caminho de instalação dos exemplos do módulo. |`/usr/local/shared/examples/ruby19/patsy` |=== Uma lista completa das variáveis ​​disponíveis pode ser encontrada em [.filename]#/usr/ports/Mk/bsd.ruby.mk#. [[using-sdl]] == Usando SDL O `USE_SDL` é usado para auto configurar as dependências para os ports que usam uma biblioteca baseada em SDL como o package:devel/sdl12[] e o package:graphics/sdl_image[]. Estas bibliotecas SDL para a versão 1.2 são reconhecidas: * sdl: package:devel/sdl12[] * console: package:devel/sdl_console[] * gfx: package:graphics/sdl_gfx[] * image: package:graphics/sdl_image[] * mixer: package:audio/sdl_mixer[] * mm: package:devel/sdlmm[] * net: package:net/sdl_net[] * pango: package:x11-toolkits/sdl_pango[] * sound: package:audio/sdl_sound[] * ttf: package:graphics/sdl_ttf[] Estas são as bibliotecas SDL para a versão 2.0 reconhecidas: * sdl: package:devel/sdl20[] * gfx: package:graphics/sdl2_gfx[] * image: package:graphics/sdl2_image[] * mixer: package:audio/sdl2_mixer[] * net: package:net/sdl2_net[] * ttf: package:graphics/sdl2_ttf[] Portanto, se um port tiver uma dependência do package:net/sdl_net[] e do package:audio/sdl_mixer[], a sintaxe será: [.programlisting] .... USE_SDL= net mixer .... A dependência package:devel/sdl12[], a qual é exigida por package:net/sdl_net[] e package:audio/sdl_mixer[], é automaticamente adicionada também. Usar `USE_SDL` com entradas para o SDL 1.2, irá automaticamente: * Adicionar uma dependência em sdl12-config para `BUILD_DEPENDS` * Adicionar a variável `SDL_CONFIG` em `CONFIGURE_ENV` * Adicionar as dependências das bibliotecas selecionadas ao `LIB_DEPENDS` Usar `USE_SDL` com entradas para o SDL 2.0, irá automaticamente: * Adicionar uma dependência em sdl2-config para `BUILD_DEPENDS` * Adicionar a variável `SDL2_CONFIG` ao `CONFIGURE_ENV` * Adicionar as dependências das bibliotecas selecionadas ao `LIB_DEPENDS` [[using-wx]] == Usando wxWidgets Esta seção descreve o status das bibliotecas wxWidgets na árvore de ports e sua integração com o sistema de ports. [[wx-introduction]] === Introdução Existem muitas versões das bibliotecas do wxWidgets que entram em conflito entre elas (instalam arquivos com o mesmo nome). Na árvore de ports este problema foi resolvido instalando cada versão sob um nome diferente usando sufixos de número de versão. A desvantagem óbvia disso é que cada aplicativo precisa ser modificado para encontrar a versão esperada. Felizmente, a maioria dos aplicativos chama o script `wx-config` para determinar os sinalizadores necessários para o compilador e o vinculador. O script é nomeado de maneira diferente para cada versão disponível. A maioria dos aplicativos respeita uma variável de ambiente ou aceita um argumento de configuração para especificar o script `wx-config` que deve ser chamado. Caso contrário, eles têm que ser corrigidos. [[wx-version]] === Seleção de Versão Para fazer o port usar uma versão específica do wxWidgets existem duas variáveis disponíveis para definir (se apenas uma for definida, a outra será definida para um valor padrão): [[wx-ver-sel-table]] .Variáveis ​​para Selecionar as Versões do wxWidgets [cols="1,1,1", frame="none", options="header"] |=== | Variável | Descrição | Valor padrão |`USE_WX` |Lista de versões que o port pode usar |Todas as versões disponíveis |`USE_WX_NOT` |Lista de versões que o port não pode usar |Nenhum |=== As versões disponíveis do wxWidgets e os ports correspondentes na árvore são: [[wx-widgets-versions-table]] .Versões Disponíveis do wxWidgets [cols="1,1", frame="none", options="header"] |=== | Versão | Port |`2.8` |package:x11-toolkits/wxgtk28[] |`3.0` |package:x11-toolkits/wxgtk30[] |=== As variáveis ​​em <> podem ser definidas para uma ou mais dessas combinações separadas por espaços: [[wx-widgets-versions-specification]] .Especificações de Versão do wxWidgets [cols="1,1", frame="none", options="header"] |=== | Descrição | Exemplo |Versão única |`2.8` |Range ascendente |`2.8+` |Range descendente |`3.0-` |Range total (deve ser crescente) |`2.8-3.0` |=== Também existem algumas variáveis ​​para selecionar as versões preferidas entre as disponíveis. Elas podem ser configuradas para uma lista de versões, as primeiras terão maior prioridade. [[wx-widgets-preferred-version]] .Variáveis para selecionar as versões preferidas do wxWidgets [cols="1,1", frame="none", options="header"] |=== | Nome | Desenhado para |`WANT_WX_VER` |o port |`WITH_WX_VER` |o usuário |=== [[wx-components]] === Seleção de Componentes Existem outras aplicações que, apesar de não serem bibliotecas wxWidgets, estão relacionadas a eles. Estas aplicações podem ser especificadas em `WX_COMPS`. Estes componentes estão disponíveis: [[wx-widgets-components-table]] .Componentes wxWidgets Disponíveis [cols="1,1,1", frame="none", options="header"] |=== | Nome | Descrição | Restrição de versão |`wx` |biblioteca principal |nenhum |`contrib` |bibliotecas contribuídas |`none` |`python` |wxPython(ligações Python) |`2.8-3.0` |=== O tipo de dependência pode ser selecionado para cada componente, adicionando-se um sufixo separado por um ponto-e-vírgula. Se não estiver presente, será usado um tipo padrão (veja <>). Estes tipos estão disponíveis: [[wx-widgets-dependency-table]] .Tipos de Dependências wxWidgets Disponíveis [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`build` |Componente é necessário para a compilação, equivalente a `BUILD_DEPENDS` |`run` |O componente é necessário para execução, equivalente a `RUN_DEPENDS` |`lib` |O componente é necessário para a compilação e execução, equivalente a `LIB_DEPENDS` |=== Os valores padrão para os componentes estão detalhados nesta tabela: [[wx-def-dep-types]] .Tipos de Dependência Padrão do wxWidgets [cols="1,1", frame="none", options="header"] |=== | Componente | Tipo de dependência |`wx` |`lib` |`contrib` |`lib` |`python` |`run` |`mozilla` |`lib` |`svg` |`lib` |=== [[wx-components-example]] .Selecionando Componentes wxWidgets [example] ==== Este fragmento corresponde a um port que usa wxWidgets versão `2.4` e suas bibliotecas contribuídas. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx contrib .... ==== [[wx-version-detection]] === Detectando Versões Instaladas Para detectar uma versão instalada, defina `WANT_WX`. Se não estiver definido para uma versão específica, os componentes terão um sufixo de versão. O `HAVE_WX` será preenchido após a detecção. [[wx-ver-det-example]] .Detectando as versões instaladas wxWidgets e seus componentes [example] ==== Este fragmento pode ser usado em um port que usa wxWidgets se estiver instalado ou uma opção estiver selecionada. [.programlisting] .... WANT_WX= yes .include .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8) USE_WX= 2.8 CONFIGURE_ARGS+= --enable-wx .endif .... Este fragmento pode ser usado em um port que permite suporte ao wxPython se ele estiver instalado ou se uma opção for selecionada, em adição ao wxWidgets, ambas nas versões `2.8`. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx WANT_WX= 2.8 .include .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif .... ==== [[wx-defined-variables]] === Variáveis ​​Definidas Estas variáveis ​​estão disponíveis no port (depois de definir uma de <>). [[wx-widgets-variables]] .Variáveis ​​definidas para ports que usam wxWidgets [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`WX_CONFIG` |O caminho para o script wxWidgets `wx-config` (com nome diferente) |`WXRC_CMD` |O caminho para o programa wxWidgets `wxrc` (com nome diferente) |`WX_VERSION` |A versão do wxWidgets que será usada (por exemplo,`2.6`) |=== [[wx-premk]] === Processando em [.filename]#bsd.port.pre.mk# Defina `WX_PREMK` para ser capaz de usar as variáveis ​​logo após a inclusão do [.filename]#bsd.port.pre.mk#. [IMPORTANT] ==== Ao definir `WX_PREMK`, a versão, dependências, componentes e variáveis ​​definidas não serão alteradas mesmo se alterado as variáveis ​​do port wxWidgets _depois de_ incluir o [.filename]#bsd.port.pre.mk#. ==== [[wx-premk-example]] .Usando Variáveis ​​nos Comandos wxWidgets [example] ==== Este fragmento ilustra o uso de `WX_PREMK` executando o script `wx-config` para obter a string de versão completa, atribuí-lo a uma variável e passá-lo para o programa. [.programlisting] .... USE_WX= 2.8 WX_PREMK= yes .include .if exists(${WX_CONFIG}) VER_STR!= ${WX_CONFIG} --release PLIST_SUB+= VERSION="${VER_STR}" .endif .... ==== [NOTE] ==== As variaveis wxWidgets ​​podem ser usadas com segurança em comandos quando estão dentro de targets sem a necessidade de `WX_PREMK`. ==== [[wx-additional-config-args]] === Argumentos Adicionais do `configure` Alguns scripts GNU `configure` não podem encontrar wxWidgets com apenas o conjunto de variáveis ​​de ambiente `WX_CONFIG`, exigindo argumentos adicionais. `WX_CONF_ARGS` pode ser usado para fornecê-los. [[wx-conf-args-values]] .Valores Legais para `WX_CONF_ARGS` [cols="1,1", frame="none", options="header"] |=== | Valor possível | Argumento resultante |`absolute` |`--with-wx-config=${WX_CONFIG}` |`relative` |`--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}` |=== [[using-lua]] == Usando Lua Esta seção descreve o status das bibliotecas Lua na árvore de ports e sua integração com o sistema de ports. [[lua-introduction]] === Introdução Existem muitas versões das bibliotecas Lua e interpretadores correspondentes, que entram em conflito entre eles (instalam arquivos com o mesmo nome). Na árvore de ports este problema foi resolvido instalando cada versão sob um nome diferente usando sufixos de número de versão. A desvantagem óbvia disso é que cada aplicativo precisa ser modificado para encontrar a versão esperada. Mas isto pode ser resolvido adicionando alguns sinalizadores adicionais ao compilador e ao linker. Aplicativos que usam Lua normalmente devem ser compilados para apenas uma versão. No entanto, os módulos carregáveis para Lua são compilados em flavor separado para cada versão Lua que eles suportam, e as dependências de tais módulos devem especificar o flavor usando o sufixo `@${LUA_FLAVOR}` no caminho do port. [[lua-version]] === Seleção de Versão Um port usando Lua deve ter uma linha dessa forma: [.programlisting] .... USES= lua .... Se uma versão específica de Lua, ou intervalo de versões for necessária, ela pode ser especificada como um parâmetro na forma `XY` (que pode ser usado várias vezes), `XY+`, `-XY`, ou `XY-ZA`. A versão padrão do Lua definida por meio do `DEFAULT_VERSIONS` será usada se cair no intervalo solicitado, caso contrário, a versão solicitada mais próxima do padrão será usada. Por exemplo: [.programlisting] .... USES= lua:52-53 .... Observe que nenhuma tentativa é feita para ajustar a seleção da versão com base na presença de qualquer versão Lua já instalada. [NOTE] ==== A forma `XY+` de especificação de versão não deve ser usada sem consideração cuidadosa; a API Lua muda consideravelmente em todas as versões, e ferramentas de configuração como CMake ou Autoconf frequentemente não funcionarão em versões futuras do Lua até ser atualizado para isso. ==== [[lua-version-config]] === Flags de Configuração e Compilador Software that uses Lua may have been written to auto-detect the Lua version in use. In general ports should override this assumption, and force the use of the specific Lua version selected as described above. Depending on the software being ported, this might require any or all of: * Usando `LUA_VER` como parte de um parâmetro para o script de configuração do software via `CONFIGURE_ARGS` ou `CONFIGURE_ENV` (ou equivalente para outros sistemas de compilação); * Adicionando `-I${LUA_INCDIR}`, `-L${LUA_LIBDIR}`, e `-llua-${LUA_VER}` para `CFLAGS`, `LDFLAGS`, `LIBS` respectivamente, conforme apropriado; * Altere a configuração do software ou arquivos de compilação para selecionar a versão correta. [[lua-version-flavors]] === Flavors de Versão Um port que instala um módulo Lua (em vez de um aplicativo que simplesmente faz uso do Lua) deve compilar um flavor separado para cada versão do Lua suportada . Isso é feito adicionando o parâmetro `module`: [.programlisting] .... USES= lua:module .... Um número de versão ou intervalo de versões também pode ser especificado; use uma vírgula para separar os parâmetros. Uma vez que cada flavor deve ter um nome de pacote diferente, a variável `LUA_PKGNAMEPREFIX` é fornecida e será definida com um valor apropriado; o uso pretendido é: [.programlisting] .... PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} .... Ports de módulo normalmente devem instalar arquivos apenas em `LUA_MODLIBDIR`, `LUA_MODSHAREDIR`, `LUA_DOCSDIR`, e `LUA_EXAMPLESDIR`>, todos os quais estão definidos para se referir a subdiretórios específicos da versão. A instalação de quaisquer outros arquivos deve ser feita com cuidado para evitar conflitos entre as versões. Um port (diferente de um módulo Lua) que deseja compilar um pacote separado para cada versão Lua deve usar o parâmetro `flavors`: [.programlisting] .... USES= lua:flavors .... Isso funciona da mesma maneira que o parâmetro `module` descrito acima, mas sem a suposição de que o pacote deve ser documentado como um módulo Lua (então `LUA_DOCSDIR` e `LUA_EXAMPLESDIR` não são definidos por padrão). No entanto, o port pode escolher definir `LUA_DOCSUBDIR` como um nome de subdiretório adequado (geralmente o `PORTNAME` do port, desde que não entre em conflito com o `PORTNAME` de qualquer módulo), caso em que a estrutura definirá `LUA_DOCSDIR` e `LUA_EXAMPLESDIR`. Tal como acontece com os ports de módulo, um port com flavor deve evitar a instalação de arquivos que entrariam em conflito entre as versões. Normalmente, isso é feito adicionando `LUA_VER_STR` como um sufixo para nomes de programas (por exemplo, usando <>), e de outra forma usando `LUA_VER` ou `LUA_VER_STR` como parte de quaisquer outros arquivos ou subdiretórios usados fora de `LUA_MODLIBDIR` e `LUA_MODSHAREDIR`. [[lua-defined-variables]] === Variáveis ​​Definidas Essas variáveis ​​estão disponíveis no port. [[using-lua-variables-ports]] .Variáveis ​​Definidas para Ports Que Usam Lua [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`LUA_VER` |A versão Lua que será usada (por exemplo,`5,1`) |`LUA_VER_STR` |A versão Lua sem os pontos (por exemplo,`51`) |`LUA_FLAVOR` |O nome do flavor correspondente à versão selecionada Lua, a ser usado para especificar dependências |`LUA_BASE` |O prefixo que deve ser usado para localizar o Lua (e componentes) que já estão instalados |`LUA_PREFIX` |O prefixo onde o Lua (e os seus componentes) são instalados por este port |`LUA_INCDIR` |O diretório onde os arquivos header do Lua estão instalados |`LUA_LIBDIR` |O diretório onde as bibliotecas Lua são instaladas |`LUA_REFMODLIBDIR` |O diretório no qual as bibliotecas dos módulos Lua ([.filename]#.so#) que já estão instalados podem ser encontrados |`LUA_REFMODSHAREDIR` |O diretório no qual os módulos Lua ([.filename]#.lua#) que já estão instalados podem ser encontrados |`LUA_MODLIBDIR` |O diretório no qual as bibliotecas dos módulos Lua ([.filename]#.so#) serão instalados por este port |`LUA_MODSHAREDIR` |O diretório no qual os módulos Lua ([.filename]#.lua#) serão instalados por este port |`LUA_PKGNAMEPREFIX` |O prefixo do nome do pacote usado por módulos Lua |`LUA_CMD` |O nome do interpretador Lua (exemplo `lua53`) |`LUAC_CMD` |O nome do compilador Lua (exemplo `luac53`) |=== Essas variáveis adicionais estão disponíveis para ports que especificaram o parâmetro `module`: [[using-lua-variables-modules]] .Variáveis Definidas para Ports de Módulos Lua [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`LUA_DOCSDIR` |o diretório no qual a documentação do módulo deve ser instalada. |`LUA_EXAMPLESDIR` |o diretório no qual os arquivos de exemplo do módulo devem ser instalados. |=== [[lua-examples]] === Exemplos [[lua-app-Makefile]] .Makefile para uma aplicação que utiliza Lua [example] ==== Este exemplo mostra como fazer referência a um módulo Lua necessário em tempo de execução. Observe que a referência deve especificar um flavor. [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever MAINTAINER= john@doe.tld COMMENT= Sample RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR} USES= lua .include .... ==== [[lua-mod-Makefile]] .Makefile para módulo simples de Lua [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} MAINTAINER= john@doe.tld COMMENT= Sample USES= lua:module DOCSDIR= ${LUA_DOCSDIR} .include .... ==== [[using-iconv]] == Usando `iconv` Após 2013-10-08 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]), o FreeBSD 10-CURRENT e as versões mais recentes têm um `iconv` nativo no sistema operacional. Em versões anteriores, o package:converters/libiconv[] era usado como dependência. Para softwares que precisam do `iconv`, defina `USES=iconv`. As versões do FreeBSD antes do 10-CURRENT em 2013-08-13 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]) não tem um `iconv` nativo. Nestas versões anteriores, uma dependência do package:converters/libiconv[] será adicionada automaticamente. Quando um port define `USES=iconv`, estas variáveis ​​estarão disponíveis: [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Nome da variável | Propósito | Valor antes do FreeBSD 10-CURRENT 254273(2013-08-13) | Valor após o FreeBSD 10-CURRENT 254273(2013-08-13) |`ICONV_CMD` |Diretório onde o binário `iconv` reside |`${LOCALBASE}/bin/iconv` |[.filename]#/usr/bin/iconv# |`ICONV_LIB` |argumento do `ld` para vincular ao [.filename]#libiconv# (se necessário) |`-liconv` |(vazio) |`ICONV_PREFIX` |Diretório onde a implementação do `iconv` reside (útil para configurar scripts) |`${LOCALBASE}` |[.filename]#/usr# |`ICONV_CONFIGURE_ARG` |Argumento de configuração pré-configurado para scripts de configuração |`--with-libiconv-prefix=${LOCALBASE}` |(vazio) |`ICONV_CONFIGURE_BASE` |Argumento de configuração pré-configurado para scripts de configuração |`--with-libiconv=${LOCALBASE}` |(vazio) |=== Esses dois exemplos preenchem automaticamente as variáveis ​​com o valor correto para sistemas usando respectivamente o package:converters/libiconv[] ou o `iconv` nativo: [[iconv-simple-use]] .Simples uso do `iconv` [example] ==== [.programlisting] .... USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB} .... ==== [[iconv-configure-use]] .Uso do `iconv` com `configure` [example] ==== [.programlisting] .... USES= iconv CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG} .... ==== Como mostrado acima, a variável `ICONV_LIB` estará vazia quando um `iconv` nativo estiver presente. Isso pode ser usado para detectar o `iconv` nativo e responder adequadamente. Às vezes um programa tem um argumento `ld` ou caminho de pesquisa codificado em um [.filename]#Makefile# ou no script configure. Essa abordagem pode ser usada para resolver esse problema: [[iconv-reinplace]] .Corrigindo Hardcoded `-liconv` [example] ==== [.programlisting] .... USES= iconv post-patch: @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile .... ==== Em alguns casos, é necessário definir valores alternativos ou executar operações dependendo se há um `iconv` nativo. O [.filename]#bsd.port.pre.mk# deve ser incluído antes de testar o valor de `ICONV_LIB`: [[iconv-conditional]] .Verificando Disponibilidade do `iconv` Nativo [example] ==== [.programlisting] .... USES= iconv .include post-patch: .if empty(ICONV_LIB) # native iconv detected @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh .endif .include .... ==== [[using-xfce]] == Usando o Xfce Ports que precisam de bibliotecas ou aplicações Xfce, utilizam `USES=xfce`. Dependencias específicas de bibliotecas e aplicativos Xfce são definidas com valores atribuídos a `USE_XFCE`. Eles são definidos em [.filename]#/usr/ports/Mk/Uses/xfce.mk#. Os valores possíveis são: .Valores de `USE_XFCE` garcon:: package:sysutils/garcon[] libexo:: package:x11/libexo[] libgui:: package:x11-toolkits/libxfce4gui[] libmenu:: package:x11/libxfce4menu[] libutil:: package:x11/libxfce4util[] painel:: package:x11-wm/xfce4-panel[] thunar:: package:x11-fm/thunar[] xfconf:: package:x11/xfce4-conf[] [[use-xfce]] .Exemplo de `USES=xfce` [example] ==== [.programlisting] .... USES= xfce USE_XFCE= libmenu .... ==== [[use-xfce-gtk2]] .Usando os Próprios Widgets GTK2 do Xfce [example] ==== Neste exemplo, o aplicativo portado usa os widgets específicos do GTK2, o package:x11/libxfce4menu[] e o package:x11/xfce4-conf[]. [.programlisting] .... USES= xfce:gtk2 USE_XFCE= libmenu xfconf .... ==== [TIP] ==== Os componentes Xfce incluídos dessa maneira incluirão automaticamente todas as dependências necessárias. Não é mais necessário especificar a lista inteira. Se o port precisar apenas de package:x11-wm/xfce4-panel[], use: [.programlisting] .... USES= xfce USE_XFCE= panel .... Não há necessidade de listar os componentes que o package:x11-wm/xfce4-panel[] precisa para ele mesmo, desta forma: [.programlisting] .... USES= xfce USE_XFCE= libexo libmenu libutil panel .... Contudo, os componentes Xfce e as dependências do port que não dependem do Xfce devem ser incluídas explicitamente. Não conte com um componente Xfce para fornecer uma sub-dependência diferente de si para o port principal. ==== [[using-databases]] == Usando Bancos de Dados Utilize uma das macros `USES` de <> para adicionar a dependência de um banco de dados. [[using-databases-uses]] .Banco de Dados de Macros `USES` [cols="1,1", frame="none", options="header"] |=== | Base de Dados | Macro USES |Berkeley DB -|<> +|crossref:uses[uses-bdb,`bdb`] |MariaDB, MySQL, Percona -|<> +|crossref:uses[uses-mysql,`mysql`] |PostgreSQL -|<> +|crossref:uses[uses-pgsql,`pgsql`] |SQLite -|<> +|crossref:uses[uses-sqlite,`sqlite`] |=== [[using-databases-bdb-ex1]] .Usando o Berkeley DB 6 [example] ==== [.programlisting] .... USES= bdb:6 .... -Veja <> para maiores informações. +Veja crossref:uses[uses-bdb,`bdb`] para maiores informações. ==== [[using-databases-mysql-ex1]] .Usando MySQL [example] ==== Quando um port precisa da biblioteca cliente do MySQL, adicione [.programlisting] .... USES= mysql .... -Veja <> para mais informações. +Veja crossref:uses[uses-mysql,`mysql`] para mais informações. ==== [[using-databases-pgsql-ex1]] .Usando PostgreSQL [example] ==== Quando um port precisar do servidor PostgreSQL versão 9.6 ou posterior, adicione [.programlisting] .... USES= pgsql:9.6+ WANT_PGSQL= server .... -Veja <> para mais informações. +Veja crossref:uses[uses-pgsql,`pgsql`] para mais informações. ==== [[using-databases-sqlite-ex1]] .Usando SQLite 3 [example] ==== [.programlisting] .... USES= sqlite:3 .... -Veja <> para mais informações. +Veja crossref:uses[uses-sqlite,`sqlite`] para mais informações. ==== [[rc-scripts]] == Iniciando e Parando Serviços (com scripts `rc`) Os scripts [.filename]#rc.d# são usados ​​para iniciar serviços na inicialização do sistema e para fornecer aos administradores uma maneira padrão de parar, iniciar e reiniciar o serviço. Ports se integram ao sistema de estrutura do [.filename]#rc.d#. Detalhes sobre seu uso podem ser encontrados no extref:{handbook}config-tuning[capitulo sobre rc.d, configtuning-rcd] do handbook. A explicação detalhada dos comandos disponíveis é fornecida em man:rc[8] e man:rc.sub[8]. Finalmente, existe um extref:{rc-scripting}[artigo] sobre aspectos práticos do sistema de scripts do [.filename]#rc.d#. Com um port mítico chamado _doorman_, o qual precisa iniciar um daemon _doormand_. Adicione o seguinte ao [.filename]#Makefile#: [.programlisting] .... USE_RC_SUBR= doormand .... Vários scripts podem ser listados e serão instalados. Os scripts devem ser colocados no subdiretório [.filename]#files# e um sufixo `.in` deve ser adicionado ao nome do arquivo. Expansões padrões `SUB_LIST` serão executadas neste arquivo. Usar as expansões `%%PREFIX%%` e `%%LOCALBASE%%` também é fortemente encorajado. Veja mais sobre a `SUB_LIST` na <>. A partir do FreeBSD 6.1-RELEASE, scripts locais [.filename]#rc.d# (incluindo aqueles instalados pelos ports) estão incluídos no man:rcorder[8] do sistema base. Um exemplo simples de script [.filename]#rc.d# para iniciar o daemon doormand: [.programlisting] .... #!/bin/sh # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ # # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown # # Add these lines to /etc/rc.conf.local or /etc/rc.conf # to enable this service: # # doormand_enable (bool): Set to NO by default. # Set it to YES to enable doormand. # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf # by default. . /etc/rc.subr name=doormand rcvar=doormand_enable load_rc_config $name : ${doormand_enable:="NO"} : ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"} command=%%PREFIX%%/sbin/${name} pidfile=/var/run/${name}.pid command_args="-p $pidfile -f $doormand_config" run_rc_command "$1" .... A menos que haja uma boa razão para iniciar o serviço mais cedo, ou ele seja executado como um usuário específico (diferente de root), todos os scripts de ports devem usar: [.programlisting] .... REQUIRE: LOGIN .... Se o script de inicialização iniciar um daemon que deve ser desligado, o seguinte acionará uma parada do serviço no desligamento do sistema: [.programlisting] .... KEYWORD: shutdown .... Se o script não está iniciando um serviço persistente, isso não é necessário. Para os elementos de configuração opcional o estilo "=" de atribuição de variável padrão é preferível ao estilo ":=", já que o primeiro define um valor padrão apenas se a variável não estiver definida, e o segundo define um se a variável não está definida _ou_ se ela é nula. Um usuário pode muito bem incluir algo como: [.programlisting] .... doormand_flags="" .... no seu [.filename]#rc.conf.local#, e uma substituição de variável usando ":=" substituirá inadequadamente a intenção do usuário. A variável `_enable` não é opcional e deve usar o ":" por padrão. [IMPORTANT] ==== -Os Ports _não devem_ iniciar e parar seus serviços durante a instalação e desinstalação. Não abuse das keywords [.filename]#plist# descritas em <> executando comandos que modificam o sistema em execução, incluindo iniciar ou interromper serviços. +Os Ports _não devem_ iniciar e parar seus serviços durante a instalação e desinstalação. Não abuse das keywords [.filename]#plist# descritas em crossref:plist[plist-keywords-base-exec, "@preexec command, @postexec command, @preunexec command, @postunexec command"] executando comandos que modificam o sistema em execução, incluindo iniciar ou interromper serviços. ==== [[rc-scripts-checklist]] === Pre-Commit Checklist Antes de contribuir um port com um script [.filename]#rc.d#, e mais importante, antes de realizar o commit de um, por favor consulte esta lista de verificação para ter certeza de que ele está pronto. O port package:devel/rclint[] pode verificar a maioria destes itens, mas não substitui uma revisão adequada. [.procedure] ==== . Se este é um novo arquivo, ele tem uma extensão [.filename]#.sh#? Se assim for, isso deve ser mudado para apenas [.filename]#file.in# uma vez que os arquivos [.filename]#rc.d# não podem terminar com essa extensão. . O arquivo tem uma tag `$FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $`? . O nome do arquivo (menos [.filename]#.in#), a linha `PROVIDE` e `$` _name_ são as mesmas? O nome do arquivo ao corresponder com o `PROVIDE` irá facilitar a depuração, especialmente para problemas de man:rcorder[8]. Combinar o nome do arquivo e o `$` _name_ torna mais fácil descobrir quais variáveis ​​são relevantes no [.filename]#rc.conf[.local]#. Isso também é uma política para todos os novos scripts, incluindo aqueles no sistema base. . A linha `REQUIRE` está definida para `LOGIN`? Isso é obrigatório para scripts que são executados como um usuário não root. Se ele for executado como root, há uma boa razão para ele ser executado antes de `LOGIN`? Caso contrário, ele deve ser executado depois para que os scripts locais possam ser agrupados em um ponto no man:rcorder[8] depois que quase tudo no sistema base já estiver rodando. . O script inicia um serviço persistente? Em caso afirmativo, ele deve ter o `KEYWORD: shutdown`. . Certifique-se de que não há um `KEYWORD: FreeBSD` presente. Isto não foi necessário nem desejável durante anos. Isto também é uma indicação de que o novo script foi copiado/colado de um script antigo, portanto, um cuidado extra deve ser dado à revisão. . Se o script usa uma linguagem interpretada como o `perl`, o `python` ou o `ruby`, certifique-se de que o `command_interpreter` está definido adequadamente, por exemplo, para o Perl, adicione `PERL=${PERL}` para a `SUB_LIST` e utilize `%%PERL%%`. De outra forma, + [source,shell] .... # service name stop .... + provavelmente não funcionará corretamente. Consulte man:service[8] para maiores informações. . Todas as ocorrências de [.filename]#/usr/local# foram substituídas por `%%PREFIX%%`? . As atribuições das variáveis ​​padrão vêm depois de `load_rc_config`? . Existem atribuições padrões para sequências vazias? Elas devem ser removidas, mas verifique se a opção está documentada nos comentários na parte superior do arquivo. . As variáveis ​​definidas estão realmente sendo utilizadas no script? . As opções listadas no padrão _name_ `_flags` são realmente obrigatórias? Se assim for, elas devem estar em `command_args`. A opção `-d` é uma flag vermelha (com o perdão do trocadilho) aqui, já que geralmente é a opção de "daemonizar" o processo e, portanto, é realmente obrigatório. . O `name_flags` nunca deve ser incluído em `command_args` (e vice-versa, embora esse erro seja menos comum). . O script executa qualquer código incondicionalmente? Isso é desaprovado. Normalmente, essas coisas devem ser tratadas através de um `start_precmd`. . Todos os testes booleanos devem usar a função `checkyesno`. Nenhum teste deve usar `[Yy][Ee][Ss]`, etc. . Se houver um loop (por exemplo, esperando que algo inicie), ele tem um contador para terminar o loop? Não queremos que a inicialização seja bloqueada para sempre se houver um erro. . O script cria arquivos ou diretórios que precisam de permissões específicas, por exemplo, um [.filename]#pid# que precisa ser de propriedade do usuário que executa o processo? Em vez da rotina tradicional man:touch[1]/man:chown[8]/man:chmod[1], considere usar man:install[1] com os argumentos de linha de comando apropriados para fazer todo o procedimento com um passo. ==== [[users-and-groups]] == Adicionando Usuários e Grupos Alguns ports exigem que uma conta de usuário específica esteja presente, geralmente para daemons executados como esse usuário. Para esses ports, escolha um UID _único_ entre 50 a 999 e registre-o em [.filename]#ports/UIDs# (para usuários) e em [.filename]#ports/GIDs#(para grupos). A identificação única deve ser a mesma para usuários e grupos. Por favor, inclua um patch para estes dois arquivos quando for necessário que um novo usuário ou grupo seja criado para o port. Então use `USERS` e `GROUPS` dentro do [.filename]#Makefile# e o usuário será criado automaticamente ao instalar o port. [.programlisting] .... USERS= pulse GROUPS= pulse pulse-access pulse-rt .... A lista atual de UIDs e GIDs reservados pode ser encontrada em [.filename]#ports/UIDs# e [.filename]#ports/GIDs#. [[requiring-kernel-sources]] == Ports que Dependem dos Fontes do kernel Alguns ports (como módulos carregáveis ​​do kernel) precisam dos arquivos fonte do kernel para que o port possa ser compilado. Aqui está a maneira correta de determinar se o usuário os instalou: [.programlisting] .... USES= kmod .... Além desta verificação, o recurso `kmod` cuida da maioria dos itens que esses ports precisam levar em consideração. [[go-libs]] == Bibliotecas Go Os ports não devem empacotar ou instalar bibliotecas Go ou código-fonte. Os ports Go devem baixar as dependências na hora da compilação e devem instalar apenas programas que os usuários precisam, e não o que os desenvolvedores Go precisam. Ports devem (por ordem de preferência): * Usar as dependências fornecidas no código fonte do pacote. * Baixar as versões das dependências especificadas pelo upstream (no caso do go.mod, vendor.json ou similar). * Como um último recurso (as dependências não estão incluídas e nem as versões foram especificadas exatamente) busque as versões das dependências disponíveis no momento do desenvolvimento/release. [[haskell-libs]] == Bibliotecas Haskell Assim como na linguagem Go, Ports não devem empacotar ou instalar as bibliotecas Haskell. Os ports Haskell devem vincular estaticamente a suas dependências e buscar todos os arquivos de distribuição no estágio fetch. [[shell-completion]] == Arquivos Shell Completion Muitos shells modernos (incluindo bash, tcsh e zsh) suportam parâmetro e/ou opção de tab-completion. Esse suporte geralmente vem de arquivos completion, os quais contêm as definições de como as tabs completion funcionarão para um determinado comando. As vezes ports vem com seus arquivos completion, ou os mantenedores de ports podem ter criado um eles mesmos. Quando disponível, os arquivos de completion devem sempre ser instalados. Não é necessário fazer uma opção para eles. Apesar que se uma opção for usada, sempre habilite-a em `OPTIONS_DEFAULT`. [[shell-completion-paths]] .Caminhos dos arquivos shell completion [cols="1,1", frame="none"] |=== |`bash` |[.filename]#${PREFIX}/etc/bash_completion.d# |`zsh` |[.filename]#${PREFIX}/shared/zsh/site-functions# |=== Não registre nenhuma dependência nos próprios shells. diff --git a/documentation/content/pt-br/books/porters-handbook/testing/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/testing/_index.adoc similarity index 99% rename from documentation/content/pt-br/books/porters-handbook/testing/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/testing/_index.adoc index 4b01c787bc..d116b1b1ed 100644 --- a/documentation/content/pt-br/books/porters-handbook/testing/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/testing/_index.adoc @@ -1,534 +1,534 @@ --- title: Capítulo 10. Testando o Port prev: books/porters-handbook/pkg-files next: books/porters-handbook/upgrading --- [[testing]] = Testando o Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[make-describe]] == Executando `make describe` Várias das ferramentas de manutenção de ports do FreeBSD, tal como o man:portupgrade[1], conta com um banco de dados chamado [.filename]#/usr/ports/INDEX# o qual mantém um registro de itens tais como as dependências do port. O [.filename]#INDEX# é criado pelo [.filename]#ports/Makefile# de nível superior através do comando `make index`, que desce em cada subdiretório dos ports e executa o comando `make describe` lá. Desta forma, se o `make describe` falhar em qualquer port, ninguém poderá gerar o [.filename]#INDEX# e muitas pessoas rapidamente se tornarão infelizes. [NOTE] ==== -É importante poder gerar este arquivo independentemente das opções presentes no [.filename]#make.conf# então evite fazer coisas como usar declarações `.error` quando (por exemplo) uma dependência não estiver satisfeita. (Veja <>.) +É importante poder gerar este arquivo independentemente das opções presentes no [.filename]#make.conf# então evite fazer coisas como usar declarações `.error` quando (por exemplo) uma dependência não estiver satisfeita. (Veja crossref:porting-dads[dads-dot-error,Evite o Uso do Construtor `.error`].) ==== E se o `make describe` produzir uma string em vez de uma mensagem de erro, provavelmente está tudo certo. Veja o [.filename]#bsd.port.mk# para saber o significado da string gerada. Note também que rodar uma versão recente do `portlint` (conforme especificado na próxima seção) executará o `make describe` automaticamente. [[testing-portlint]] == Portlint Verifique o port com <> antes de submete-lo ou de fazer o seu commit. O `portlint` alerta sobre muitos erros comuns, tanto funcionais quanto de estilo. Para um novo (ou um repocopiado) port , `portlint -A` é o uso mais completo; para um port existente, `portlint -C` é suficiente. O `portlint` usa uma técnica heurística para tentar descobrir erros, pode produzir avisos falso-positivos. Além disso, ocasionalmente, algo que é sinalizado como um problema, pode não ter uma outra forma de ser realizado por limitações no framework dos ports. Em caso de dúvida, a melhor coisa a fazer é perguntar na http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[Lista de discussão de ports do FreeBSD]. [[testing-porttools]] == Ferramentas do Ports O programa package:ports-mgmt/porttools[] faz parte da Coleção de Ports. O `port` é o script front-end, que pode ajudar a simplificar o trabalho de teste. Sempre que um novo port ou uma atualização de um já existente precisar de teste, use `port test` para testar o port, incluindo a verificação <>. Este comando também detecta e lista todos os arquivos que não estão listados no [.filename]#pkg-plist#. Por exemplo: [source,shell] .... # port test /usr/ports/net/csup .... [[porting-prefix]] == `PREFIX` e `DESTDIR` `PREFIX` determina onde o port será instalado. O padrão é [.filename]#/usr/local#, mas pode ser definido pelo usuário para um caminho personalizado como [.filename]#/opt#. O port deve respeitar o valor dessa variável. O `DESTDIR`, se definido pelo usuário, determina o ambiente alternativo completo, geralmente uma jail ou um sistema instalado montado em outro local que não seja o [.filename]#/#. Um port será realmente instalado no [.filename]#DESTDIR/PREFIX#, e registrado no banco de dados de pacotes em [.filename]#DESTDIR/var/db/pkg#. Como o `DESTDIR` é tratado automaticamente pela infraestrutura de ports com o man:chroot[8]. Não há necessidade de modificações ou qualquer cuidado extra para escrever ports compatíveis com o `DESTDIR`. O valor de `PREFIX` será definido para `LOCALBASE` (o valor padrão é [.filename]#/usr/local#). E se `USE_LINUX_PREFIX` estiver definido o `PREFIX` será `LINUXBASE` (o valor padrão é [.filename]#/compat/linux#). Evitar o uso do caminho [.filename]#/usr/local# codificado no fonte tornam o port muito mais flexível e capaz de atender às necessidades de outros sites. Muitas vezes, isso pode ser feito substituindo as ocorrências de [.filename]#/usr/local# nos vários [.filename]##Makefile##s dos ports por `${PREFIX}`. Essa variável é transmitida automaticamente para todos os estágios dos processos de compilação e instalação. Verifique se o aplicativo não está instalando arquivos em [.filename]#/usr/local# ao invés de `PREFIX`. Um teste rápido para esses caminhos codificados é: [source,shell] .... % make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` .... Se alguma coisa for instalada fora do `PREFIX`, o processo de criação de pacotes irá reclamar que não pode encontrar os arquivos. -Além disso, vale a pena verificar o mesmo em relação ao suporte a diretórios stage (veja <>): +Além disso, vale a pena verificar o mesmo em relação ao suporte a diretórios stage (veja crossref:special[staging,Staging]): [source,shell] .... % make stage && make check-plist && make stage-qa && make package .... * O `check-plist` verifica arquivos ausentes do plist e arquivos no plist que não são instalados pelo port. * O `stage-qa` verifica problemas comuns como shebang incorretas, links simbólicos apontando para fora do diretório de stage, arquivos setuid e bibliotecas não removidas... Esses testes não encontrarão caminhos codificados dentro dos arquivos do port, nem verificarão se o `LOCALBASE` está sendo usado para se referir corretamente a arquivos de outros ports. O port instalado temporariamente em [.filename]#/var/tmp/`make -V PORTNAME`# deve ser testado quanto à operação correta para garantir que não haja problemas com os caminhos. O `PREFIX` não deve ser definido explicitamente em um [.filename]#Makefile# do port. Usuários instalando o port podem ter definido a variável `PREFIX` para um local personalizado e o port deve respeitar essa configuração. Referencie programas e arquivos de outros ports com as variáveis ​​mencionadas acima, não com nomes de caminho explícitos. Por exemplo, se o port exigir uma macro `PAGER` para ter o nome de caminho completo para o `less`, não use um caminho literal para [.filename]#/usr/local/bin/less#. Em vez disso, use `${LOCALBASE}`: [.programlisting] .... -DPAGER=\"${LOCALBASE}/bin/less\" .... O caminho com `LOCALBASE` é muito provável que ainda funcione se o administrador do sistema mudou toda a arvore [.filename]#/usr/local# para algum outro lugar. [TIP] ==== Todos esses testes são feitos automaticamente ao executar `poudriere testport` ou `poudriere bulk -t`. É altamente recomendável que cada contribuidor de ports instale e teste seus ports com ele. Veja <> para maiores informações. ==== [[testing-poudriere]] == Poudriere Para um contribuidor de ports, o Poudriere é uma das mais importantes e úteis ferramentas de teste e compilação. Suas principais características incluem: * Compilação em massa de toda a árvore de ports, subconjuntos específicos da árvore de ports, ou um único port incluindo suas dependências * Empacotamento automático do resultados de compilação * Geração de arquivos de log de compilação por port * Fornecer um repositório man:pkg[8] assinado * Testar a compilação do port antes de enviar um patch para o rastreador de bugs do FreeBSD ou antes de fazer o commit para a árvore de ports * Testar a compilação bem-sucedida de ports usando opções diferentes Porque o Poudriere realiza a sua compilação em um ambiente de man:jail[8] limpo e usa características do man:zfs[8], ele tem várias vantagens sobre os testes tradicionais no sistema host: * Ele não polui o ambiente do host: sem arquivos sobrando, sem remoções acidentais, sem alterações nos arquivos de configuração existentes. * Ele verifica o [.filename]#pkg-plist# para entradas ausentes ou supérfluas * Committers de ports às vezes pedem um log do Poudriere juntamente com a apresentação de um patch para avaliar se o patch está pronto para integração na árvore de ports Ele também é muito simples de configurar e usar, não tem dependências e será executado em qualquer versão suportada do FreeBSD. Esta seção mostra como instalar, configurar e executar o Poudriere como parte do fluxo de trabalho normal de um contribuidor de ports. Os exemplos nesta seção mostram um layout de arquivo padrão, como padrão no FreeBSD. Substitua quaisquer alterações locais de acordo. A árvore de ports, representada por `${PORTSDIR}`, está localizada em [.filename]#/usr/ports#. Ambos `${LOCALBASE}` e `${PREFIX}` são [.filename]#/usr/local# por padrão. [[testing-poudriere-installing]] === Instalando o Poudriere O Poudriere está disponível na árvore de ports em package:ports-mgmt/poudriere[]. Ele pode ser instalado usando o man:pkg[8] ou a partir do ports: [source,shell] .... # pkg install poudriere .... ou [source,shell] .... # make -C /usr/ports/ports-mgmt/poudriere install clean .... Há também uma versão de trabalho em andamento do Poudriere que acabará por se tornar o próximo release. Ele está disponível em package:ports-mgmt/poudriere-devel[]. Esta versão de desenvolvimento é usada para as compilações oficiais de pacotes do FreeBSD, então é bem testada. Muitas vezes tem novos recursos interessantes. Um committer de ports desejará usar a versão de desenvolvimento porque é o que é usado na produção e possui todos os novos recursos que farão com que tudo esteja exatamente correto. Um colaborador não precisará necessariamente deles, pois as correções mais importantes são sempre incorporadas na versão release. A principal razão para o uso da versão de desenvolvimento para compilar os pacotes oficiais é porque é mais rápido, de uma forma que encurtará uma compilação completa de 18 horas para 17 horas ao usar um servidor de 32 CPUs high-end com 128GB de RAM. Essas otimizações não terão muita importância ao compilar ports em uma máquina desktop. [[testing-poudriere-setup]] === Configurando o Poudriere O port instala um arquivo de configuração padrão, o [.filename]#/usr/local/etc/poudriere.conf#. Cada parâmetro é documentado no arquivo de configuração em man:poudriere[8]. Aqui está um arquivo de configuração mínimo de exemplo: [.programlisting] .... ZPOOL=tank ZROOTFS=/poudriere BASEFS=/poudriere DISTFILES_CACHE=/usr/ports/distfiles RESOLV_CONF=/etc/resolv.conf FREEBSD_HOST=ftp://ftp.freebsd.org SVN_HOST=svn.FreeBSD.org .... `ZPOOL`:: O nome do pool de armazenamento do ZFS que o Poudriere deve usar. Deve ser listado na saída de `zpool status`. `ZROOTFS`:: A raiz dos sistemas de arquivos gerenciados do Poudriere. Esta entrada fará com que o Poudriere crie o sistema de arquivo man:zfs[8] sob `tank/poudriere`. `BASEFS`:: O ponto de montagem da raiz do sistema de arquivo Poudriere. Esta entrada fará com que o Poudriere monte o `tank/poudriere` no `/poudriere`. `DISTFILES_CACHE`:: Define onde os distfiles são armazenados. Neste exemplo, o Poudriere e o host compartilham o diretório de armazenamento dos distfiles. Isso evita o download de tarballs que já estão presentes no sistema. Por favor, crie este diretório se ele ainda não existir, para que o Poudriere possa encontrá-lo. `RESOLV_CONF`:: Utiliza o [.filename]#/etc/resolv.conf# do host dentro do jails para a resolução de DNS. Isso é necessário para que as jails possam resolver as URLs dos distfiles durante o download. Não é necessário ao usar um proxy. Consulte o arquivo de configuração padrão para a configuração de proxy. `FREEBSD_HOST`:: O servidor FTP/HTTP a ser usado quando as jails são instaladas a partir de versões do FreeBSD e atualizadas com o man:freebsd-update[8]. Escolha um servidor cuja localização esteja próxima, por exemplo, se a máquina estiver localizada na Austrália, use `ftp.au.freebsd.org`. `SVN_HOST`:: O servidor de onde as jails são instaladas e atualizadas ao usar o Subversion. Também usado para a árvore de ports quando não estiver usando o man:portsnap[8]. Mais uma vez, escolha um local próximo. Uma lista de espelhos oficiais do Subversion podem ser encontrados na seção sobre extref:{handbook}mirrors[Subversion, svn-mirrors] do Handbook do FreeBSD. [[testing-poudriere-create-jails]] === Criando Poudriere Jails Crie as jails de base que serão usadas pelo Poudriere para as compilações: [source,shell] .... # poudriere jail -c -j 113Ramd64 -v 11.3-RELEASE -a amd64 .... Baixe a versão `11.3-RELEASE` para `amd64` do servidor FTP dado por `FREEBSD_HOST` dentro do [.filename]#poudriere.conf#, crie o sistema de arquivos com zfs em `tank/poudriere/jails/113Ramd64`, monte-o em [.filename]#/poudriere/jails/113Ramd64# e extrai os tarballs `11.3-RELEASE` neste sistema de arquivos. [source,shell] .... # poudriere jail -c -j 11i386 -v stable/11 -a i386 -m svn+https .... Criado o `tank/poudriere/jaulas/11i386` monte-o em [.filename]#/poudriere/jails/11i386#, então confira a dica do Subversion branch do `FreeBSD-11-STABLE` a partir do `SVN_HOST` dentro do [.filename]#poudriere.conf# para dentro de [.filename]#/poudriere/jails/11i386/usr/src#, e então complete um `buildworld` e instale-o em [.filename]#/poudriere/jails/11i386#. [TIP] ==== Se uma determinada revisão do Subversion é necessária, anexe ela à string de versão. Por exemplo: [source,shell] .... # poudriere jail -c -j 11i386 -v stable/11@123456 -a i386 -m svn+https .... ==== [NOTE] ==== Embora seja possível compilar uma versão mais nova do FreeBSD em uma versão mais antiga, na maioria das vezes ela não irá executar. Por exemplo, se uma jail `stable/11` é necessária, o host terá que rodar `stable/11` também. Rodar `11.3-RELEASE` não é o suficiente. ==== [NOTE] ==== Para criar uma jail Poudriere para o `13.0-CURRENT`: [source,shell] .... # poudriere jail -c -j 13amd64 -v head -a amd64 -m svn+https .... Para executar uma jail `13.0-CURRENT` no Poudriere você deve estar rodando o `13.0-CURRENT`. Em geral, novos kernels podem ser compilados e executar jails mais antigas. Por exemplo, um kernel `13.0-CURRENT` pode compilar e executar uma jail `11.3-STABLE` no Poudriere se a opção de kernel `COMPAT_FREEBSD11` tiver sido compilada (habilitada por padrão na configuração do kernel [.filename]#GENERIC# do `13.0-CURRENT`). ==== [CAUTION] ==== O protocolo padrão `svn` funciona normalmente, mas não é muito seguro. Usar `svn+https` juntamente com a verificação do fingerpprint SSL do servidor remoto é aconselhável. Isso garantirá que os arquivos usados para compilar a jail sejam de uma fonte confiável. ==== Uma lista de jails atualmente conhecidas pelo Poudriere podem ser mostradas com `poudriere jail -l`: [source,shell] .... # poudriere jail -l JAILNAME VERSION ARCH METHOD 113Ramd64 11.3-RELEASE amd64 ftp 11i386 11.3-STABLE i386 svn+https .... [[testing-poudriere-maintaining-jails]] === Mantendo as Jails do Poudriere Atualizadas Gerenciar atualizações é muito simples. O comando: [source,shell] .... # poudriere jail -u -j JAILNAME .... atualiza a jail especificada para a versão mais recente disponível. Para releases do FreeBSD, atualiza para o patchlevel mais recente com o man:freebsd-update[8]. Para versões do FreeBSD compiladas a partir do código fonte, atualiza para a revisão mais recente na branch do Subversion. [TIP] ==== Para jails que empregam um método `svn+_*_`, é útil adicionar `-J _NumberOfParallelBuildJobs_` para acelerar a compilação aumentando o número de trabalhos de compilação paralelos utilizados. Por exemplo, se a máquina de compilação tiver 6 CPUs, use: [source,shell] .... # poudriere jail -u -J 6 -j JAILNAME .... ==== [[testing-poudriere-ports-tree]] === Configurando a Árvores de Ports para Uso com o Poudriere Existem várias maneiras de usar árvores de ports no Poudriere. A maneira mais direta é o Poudriere criar uma árvore de ports padrão para si mesmo usando man:portsnap[8] (se estiver executando FreeBSD 12.1 ou 11.4) ou Subversion (se estiver executando FreeBSD-CURRENT): [source,shell] .... # poudriere ports -c -m portsnap .... ou [source,shell] .... # poudriere ports -c -m svn+https .... Estes comandos criam `tank/poudriere/ports/default`, monta-o em [.filename]#/poudriere/ports/default# e o povoa usando o man:portsnap[8] ou Subversion. Depois disso, ele é incluído na lista de árvores de ports conhecidas: [source,shell] .... # poudriere ports -l PORTSTREE METHOD TIMESTAMP PATH default svn+https 2020-07-20 04:23:56 /poudriere/ports/default .... [NOTE] ==== Note que a árvore de ports "default" é especial. Cada um dos comandos de compilação explicados posteriormente usará implicitamente essa árvore de ports, a menos que seja especificamente especificado de outra forma. Para usar outra árvore, adicione `-p _treename_` aos comandos. ==== Embora seja útil para compilações em massa regulares, ter esta árvore de ports padrão com o método man:portsnap[8] pode não ser a melhor maneira de lidar com modificações locais para um contribuidor de ports. Assim como na criação dos jails, é possível usar um método diferente para criar a árvore de ports. Para adicionar uma árvore de ports adicional para testar modificações locais e para o desenvolvimento de ports, baixar a árvore via Subversion (como descrito acima) é preferido: [NOTE] ==== Os métodos http e https precisam que o package:devel/subversion[] seja compilado com a opção `SERF` ativada. Ela vem habilitada por padrão. ==== [TIP] ==== O método `svn` permite qualificadores extras para dizer ao Subversion exatamente como buscar os dados. Isso é explicado em man:poudriere[8]. Por exemplo, `poudriere ports -c -m svn+ssh -p subversive` usa o SSH para o checkout. ==== [[testing-poudriere-ports-tree-manual]] === Usando Árvores de Ports Gerenciadas Manualmente com o Poudriere Dependendo do fluxo de trabalho, pode ser extremamente útil usar árvores de ports que são mantidas manualmente. Por exemplo, se houver uma cópia local da árvore de ports em [.filename]#/work/ports#, aponte o Poudriere para o local: * Para o Poudriere anterior à versão 3.1.20: + [source,shell] .... # poudriere ports -c -F -f none -M /work/ports -p development .... * Para o Poudriere versão 3.1.20 e posterior: + [source,shell] .... # poudriere ports -c -m null -M /work/ports -p development .... Isto será listado na tabela de árvores conhecidas: [source,shell] .... # poudriere ports -l PORTSTREE METHOD TIMESTAMP PATH development null 2020-07-20 05:06:33 /work/ports .... [NOTE] ==== O traço ou `null` na coluna `METHOD` significa que o Poudriere nunca irá atualizar ou alterar esta árvore de ports. É de responsabilidade total do usuário a manutenção desta árvore, incluindo todas as modificações locais que podem ser usadas para testar novos ports e enviar patches. ==== [[testing-poudriere-ports-tree-updating]] === Mantendo as Árvores de Ports do Poudriere Atualizadas Tão simples quanto com as jails descritas anteriormente: [source,shell] .... # poudriere ports -u -p PORTSTREE .... Vai atualizar a _PORTSTREE_, uma árvore dada pela saída de `poudriere -l`, para a última revisão disponível nos servidores oficiais. [NOTE] ==== As arvores de ports sem um método, veja <>, não podem ser atualizadas assim. Elas devem ser atualizadas manualmente pelo mantenedor de ports. ==== [[testing-poudriere-testing-ports]] === Testando Ports Depois que as jails e as árvores de ports foram configuradas, o resultado das modificações de um colaborador na árvore de ports pode ser testado. Por exemplo, modificações locais no port package:www/firefox[] localizado em [.filename]#/work/ports/www/firefox# pode ser testado na jail 11.3-RELEASE criada anteriormente: [source,shell] .... # poudriere testport -j 113Ramd64 -p development -o www/firefox .... Isso irá compilar todas as dependências do firefox. Se uma dependência foi criada anteriormente e ainda está atualizada, o pacote pré-criado é instalado. Se uma dependência não tiver um pacote atualizado, ela será compilada com opções padrão em uma jail. Depois disso o firefox será compilado. A compilação completa de cada port será registrada em [.filename]#/poudriere/data/logs/bulk/113Ri386-development/build-time/logs#. O nome do diretório `113Ri386-development` é derivado dos argumentos para `-j` e `-p`, respectivamente. Por conveniência, um link simbólico [.filename]#/poudriere/data/logs/bulk/113Ri386-development/latest# também é mantido. O link aponta para o mais recente diretório _build-time_. Neste diretório também se encontra um [.filename]#index.html# para que possa ser possível observar o processo de compilação com um navegador web. Por padrão, o Poudriere limpa as jails e deixa os arquivos de log nos diretórios mencionados acima. Para facilitar a investigação, as jails podem ser mantidas em execução após a compilação, adicionando a opção `-i` ao `testport`: [source,shell] .... # poudriere testport -j 113Ramd64 -p development -i -o www/firefox .... Depois que a compilação é concluída, e independentemente de ter sido bem-sucedida, um shell é fornecido dentro da jail. O shell é usado para investigações adicionais. O Poudriere pode ser dito para deixar a jail em execução após a conclusão da compilação com `-i`. O Poudriere mostrará o comando para ser executado quando a jail não for mais necessária. E então é possível fazer um man:jexec[8] para dentro dele: [source,shell] .... # poudriere testport -j 113Ramd64 -p development -I -o www/firefox [...] ====>> Installing local Pkg repository to /usr/local/etc/pkg/repos ====>> Leaving jail 113Ramd64-development-n running, mounted at /poudriere/data/.m/113Ramd64-development/ref for interactive run testing ====>> To enter jail: jexec 113Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root ====>> To stop jail: poudriere jail -k -j 113Ramd64 -p development # jexec 113Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root # [do some stuff in the jail] # exit # poudriere jail -k -j 113Ramd64 -p development ====>> Umounting file systems .... Uma parte integral da infraestrutura de compilação de ports do FreeBSD é a capacidade de ajustar os ports as preferências pessoais por meio de opções. Elas podem ser testadas com o Poudriere também. Adicionando a opção `-c`: [source,shell] .... # poudriere testport -c -o www/firefox .... Apresenta o diálogo de configuração do port antes que o port seja compilado. Os ports informados após o `-o` no formato `_category_/_portname_` usará as opções especificadas, todas as dependências usarão as opções padrão. O teste de ports dependentes com opções não padrão pode ser realizado usando conjuntos, consulte <>. [TIP] ==== Ao testar ports nos quais o [.filename]#pkg-plist# é alterado durante a compilação, dependendo das opções selecionadas, é recomendável executar um teste com todas as opções selecionadas _e_ um com todas as opções desmarcadas. ==== [[testing-poudriere-sets]] === Usando Conjuntos Para todas as ações envolvendo builds, um então chamado _conjunto_ pode ser especificado usando `-z _setname_`. Um conjunto se refere a uma compilação totalmente independente. Isso permite, por exemplo, o uso de `testport` com opções não padrão para os ports dependentes. Para usar sets, o Poudriere espera uma estrutura de diretórios existente semelhante a `PORT_DBDIR`, o padrão é [.filename]#/var/db/ports# no seu diretório de configuração. Este diretório é então man:nullfs[5]-montado nas jails onde os ports e suas dependências são compilados. Normalmente, um ponto de partida adequado pode ser obtido copiando de forma recursiva o `PORT_DBDIR` para [.filename]#/usr/local/etc/poudriere.d/jailname-portname-setname-options#. Isso é descrito em detalhes em man:poudriere[8]. Por exemplo, para testar o package:www/firefox[] em um conjunto específico chamado `devset`, adicione o parâmetro `-z devset` ao comando testport: [source,shell] .... # poudriere testport -j 113Ramd64 -p development -z devset -o www/firefox .... Isso irá procurar pela existência desses diretórios nesta ordem: * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-development-devset-options# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-devset-options# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-development-options# * [.filename]#/usr/local/etc/poudriere.d/devset-options# * [.filename]#/usr/local/etc/poudriere.d/development-options# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-options# * [.filename]#/usr/local/etc/poudriere.d/options# Desta lista, o Poudriereman:nullfs[5]-monta a _primeira árvore existente_ de diretório para o diretório [.filename]#/var/db/ports# das jails de compilação. Portanto, todas as opções personalizadas são usadas para todos os ports durante essa execução do `testport`. Depois que a estrutura de diretório para um conjunto é fornecida, as opções para um port específico podem ser alteradas. Por exemplo: [source,shell] .... # poudriere options -c www/firefox -z devset .... O diálogo de configuração para o package:www/firefox[] é mostrado e as opções podem ser editadas. As opções selecionadas são salvas no set `devset`. [NOTE] ==== Poudriere é muito flexível na configuração das opções. Elas podem ser configuradas para jails específicas, árvores de ports e para vários ports por um comando. Veja man:poudriere[8] para detalhes. ==== [[testing-poudriere-make-conf]] === Fornecendo um Arquivo [.filename]#make.conf# Customizado Semelhante ao uso de conjuntos (sets), o Poudriere também usará um [.filename]#make.conf# personalizado se for fornecido. Nenhum argumento de linha de comando especial é necessário. Em vez disso, o Poudriere procura por arquivos existentes que correspondam a um esquema de nomes derivado da linha de comando. Por exemplo: [source,shell] .... # poudriere testport -j 113Ramd64 -p development -z devset -o www/firefox .... faz o Poudriere verificar a existência desses arquivos nesta ordem: * [.filename]#/usr/local/etc/poudriere.d/make.conf# * [.filename]#/usr/local/etc/poudriere.d/devset-make.conf# * [.filename]#/usr/local/etc/poudriere.d/development-make.conf# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-make.conf# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-development-make.conf# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-devset-make.conf# * [.filename]#/usr/local/etc/poudriere.d/113Ramd64-development-devset-make.conf# Ao contrário dos conjuntos, todos os arquivos encontrados serão anexados, _naquela ordem_, em um [.filename]#make.conf# dentro das jails de compilação. Assim, é possível ter variáveis gerais, destinadas a afetar todas as compilações [.filename]#/usr/local/etc/poudriere.d/make.conf#. Variáveis especiais, destinadas a afetar apenas determinadas jails ou conjuntos, podem ser setadas em arquivos especiais como [.filename]#make.conf#, assim como [.filename]#/usr/local/etc/poudriere.d/113Ramd64-development-devset-make.conf#. [[testing-poudriere-sets-perl]] .Usando [.filename]#make.conf# para Alterar o Perl Padrão [example] ==== Para compilar um conjunto com uma versão não padrão do Perl, por exemplo, `5.20`, usando um conjunto chamado `perl5-20`, crie um [.filename]#perl5-20-make.conf# com esta entrada: [.programlisting] .... DEFAULT_VERSIONS+= perl=5.20 .... [NOTE] ====== Observe o uso de `+=` de modo que, se a variável já estiver definida no [.filename]#make.conf# padrão, seu conteúdo não será sobrescrito. ====== ==== [[testing-poudriere-pruning-distfiles]] === Remoção de Distfiles Não Mais Necessários Poudriere vem com um mecanismo embutido para remover distfiles desatualizados que não são mais usados ​​por qualquer port de uma determinada árvore. O comando [source,shell] .... # poudriere distclean -p portstree .... irá escanear a pasta distfiles, `DISTFILES_CACHE` dentro do [.filename]#poudriere.conf#, contra a árvore de ports dada pelo argumento `-p _portstree_` e solicitar a remoção desses distfiles. Para pular o prompt e remover incondicionalmente todos os arquivos não utilizados, o argumento `-y` pode ser adicionado: [source,shell] .... # poudriere distclean -p portstree -y .... diff --git a/documentation/content/pt-br/books/porters-handbook/upgrading/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/upgrading/_index.adoc similarity index 96% rename from documentation/content/pt-br/books/porters-handbook/upgrading/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/upgrading/_index.adoc index 314b0022bc..7b83c25208 100644 --- a/documentation/content/pt-br/books/porters-handbook/upgrading/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/upgrading/_index.adoc @@ -1,227 +1,227 @@ --- title: Capítulo 11. Atualizando um Port prev: books/porters-handbook/testing next: books/porters-handbook/security --- [[port-upgrading]] = Atualizando um Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Quando um port não estiver na versão mais recente disponibilizada pelos autores, atualize a sua cópia de trabalho local do [.filename]#/usr/ports#. O port pode já ter sido atualizado para a nova versão. Ao trabalhar com diversos ports, provavelmente será mais fácil usar o Subversion para manter toda a coleção de ports atualizada, conforme descrito no extref:{handbook}ports[Handbook, ports-using]. Isso trará o benefício adicional de rastrear todas as dependências de ports. O próximo passo é ver se há uma atualização já pendente. Para fazer isso, existem duas opções. Há uma interface de pesquisa no https://bugs.freebsd.org/search/[Relatório de Problemas do FreeBSD (PR) ou banco de dados de bugs]. Selecione `Ports & Packages` no menu de seleção múltipla `Product` e digite o nome do port no campo `Summary`. No entanto, às vezes as pessoas esquecem de colocar o nome do port no campo Resumo de maneira não ambígua. Nesse caso, tente pesquisar o campo `Comment` na seção `Detailled Bug Information`, ou tente o <> (também conhecido como `portsmon`). Este sistema tenta classificar os PRs do port por portname. Para procurar por PRs sobre um port específico, use a http://portsmon.FreeBSD.org/portoverview.py[Visão geral de um port]. Se não houver nenhum PR pendente, o próximo passo é enviar um email para o mantenedor do port, como apresentado em `make maintainer`. Essa pessoa pode já estar trabalhando em uma atualização ou ter algum motivo para não atualizar o port neste momento (devido a, por exemplo, problemas de estabilidade da nova versão), e não há necessidade de duplicar seu trabalho. Note que os ports não mantidos são listadas com um mantenedor `ports@FreeBSD.org`, que é apenas a lista de discussão geral de ports, então enviar emails provavelmente não ajudará nesse caso. Se o mantenedor lhe pedir para fazer a atualização ou não houver mantenedor, então ajude o FreeBSD preparando a atualização! Por favor, faça isso usando o comando man:diff[1] do sistema base. Para criar um `diff` adequado para um único patch, copie o arquivo que precisa de patching para [.filename]#something.orig#, salve as alterações em [.filename]#something# e depois crie o patch: [source,shell] .... % diff -u something.orig something > something.diff .... Caso contrário, use o método `svn diff` (<>) ou copie o conteúdo do port para um diretório completamente diferente e use o resultado do man:diff[1] recursivo para os diretórios novos e antigos do port (por exemplo, se o diretório de ports modificado for chamado [.filename]#superedit# e o original está na nossa árvore como [.filename]#superedit.bak# então salve o resultado do comando `diff -ruN superedit.bak superedit`). Tanto o diff unificado ou como o de contexto é aceito, mas os committers do port geralmente preferem diffs unificados. Observe o uso da opção `-N` -- essa é a maneira correta de forçar o diff a lidar adequadamente com o caso de novos arquivos sendo adicionados ou de arquivos antigos sendo excluídos. Antes de nos enviar o diff, por favor, examine a saída para se certificar de que todas as alterações fazem sentido. (Em particular, primeiro limpe os diretórios de trabalho com `make clean`). [NOTE] ==== Se alguns arquivos foram adicionados, copiados, movidos ou removidos, adicione essas informações ao relatório de problemas, para que o committer que pegar o patch saiba quais comandos man:svn[1] executar. ==== -Para simplificar operações comuns com arquivos de patch, use `make makepatch` como descrito em <>. Existem outras ferramentas, como [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Antes de usá-lo, por favor leia [.filename]#/usr/ports/Tools/scripts/README.patchtool#. +Para simplificar operações comuns com arquivos de patch, use `make makepatch` como descrito em crossref:slow-porting[slow-patch,Patching]. Existem outras ferramentas, como [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Antes de usá-lo, por favor leia [.filename]#/usr/ports/Tools/scripts/README.patchtool#. Se o port não é mantido e você o utiliza ativamente, por favor, considere se voluntariar como o seu mantenedor. O FreeBSD tem mais de 4000 ports sem mantenedores, e esta é uma área onde mais voluntários são sempre necessários. (Para uma descrição detalhada das responsabilidades dos mantenedores, consulte a seção no extref:{developers-handbook}[Developer's Handbook, POLICIES-MAINTAINER].) Para enviar o diff, use o https://bugs.freebsd.org/submit/[formulário de envio de bugs] (no produto `Ports & Packages`, e no componente `Individual Port(s)`). Sempre inclua a categoria com o nome do port, seguido por dois pontos e uma breve descrição do problema. Exemplos: `_category/portname_: _add FOO option_`; `_category/portname_: _Update to XY_`. Por favor mencione quaisquer arquivos adicionados ou deletados na mensagem, pois eles devem ser explicitamente especificados no man:svn[1] ao fazer o commit. Não comprima ou codifique o diff. Antes de enviar o bug, revise a seção extref:{problem-reports}[Escrevendo um relatório de problema, pr-writing] no artigo Relatórios de Problemas. Ele contém muito mais informações sobre como escrever relatórios úteis de problemas. [IMPORTANT] ==== Se a atualização for motivada por preocupações de segurança ou por uma falha grave em um port que já está disponível na arvore, notifique a Equipe de Gerenciamento de Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org] para solicitar imediata recompilação e redistribuição do pacote do port. Caso contrário, usuários desavisados ​​do `pkg` continuarão a instalar a versão antiga via `pkg install` por várias semanas. ==== [NOTE] ==== Por favor, use o man:diff[1] ou `svn diff` para criar atualizações para ports existentes. Outros formatos incluem o arquivo inteiro e impossibilitam ver o que mudou. Quando os diffs não são incluídos, toda a atualização pode ser ignorada. ==== -Agora que tudo isso foi feito, leia sobre como manter-se atualizado <>. +Agora que tudo isso foi feito, leia sobre como manter-se atualizado crossref:keeping-up[keeping-up,Mantendo-se Atualizado]. [[svn-diff]] == Usando o Subversion para Criar Patches Quando possível, envie por favor um man:svn[1]diff. Eles são mais fáceis de manusear do que os diffs entre diretórios "novos e antigos". Nele é mais fácil de ver o que mudou e também é mais fácil de atualizar o diff no caso de algo ter sido modificado na Coleção de Ports desde que o diff foi gerado, ou no caso do committer pedir que algo seja corrigido. Além disso, um patch gerado com `svn diff` pode ser facilmente aplicado com `svn patch` e irá economizar algum tempo para o committer. [source,shell] .... % cd ~/my_wrkdir <.> % svn co https://svn.FreeBSD.org/ports/head/dns/pdnsd <.> % cd ~/my_wrkdir/pdnsd .... <.> Isso pode ser em qualquer lugar, é claro. Compilações de ports não se limitam ao [.filename]#/usr/ports/#. <.> O https://svn.FreeBSD.org/[svn.FreeBSD.org] é o servidor Subversion público do FreeBSD. Veja extref:{handbook}mirrors[Mirrors do Subversion, svn-mirrors] para mais informações. Enquanto estiver no diretório de ports, faça as alterações necessárias. Se você adicionar, copiar, mover ou remover um arquivo, use o `svn` para registrar essas alterações: [source,shell] .... % svn add new_file % svn copy some_file file_copy % svn move old_name new_name % svn remove deleted_file .... -Certifique-se de verificar o port usando a lista de verificação <> e <>. +Certifique-se de verificar o port usando a lista de verificação crossref:quick-porting[porting-testing,Testando o Port] e crossref:quick-porting[porting-portlint,Verificando o Port com `portlint`]. [source,shell] .... % svn status % svn update <.> .... <.> Isso tentará mesclar as diferenças entre o patch e a versão do repositório atual. Veja a saída cuidadosamente. A letra na frente de cada nome de arquivo indica o que foi feito com ele. Consulte <> para uma lista completa. [[table-svn-up]] .Prefixos de Atualização de Arquivos do Subversion [cols="1,1", frame="none"] |=== |U |O arquivo foi atualizado sem problemas. |G |O arquivo foi atualizado sem problemas (somente quando está trabalhando com um repositório remoto). |M |O arquivo foi modificado e foi mesclado sem conflitos. |C |O arquivo foi modificado e foi mesclado com conflitos. |=== E se o status `C` for exibido como resultado de um `svn update`, isso significa que algo mudou no repositório Subversion e o man:svn[1] não foi capaz de mesclar as alterações locais com as do repositório. É sempre uma boa ideia inspecionar as alterações de qualquer maneira, o man:svn[1] não sabe nada sobre a estrutura de um port, então pode (e provavelmente irá) mesclar coisas que não fazem sentido. O último passo é fazer um man:diff[1] unificado das mudanças: [source,shell] .... % svn diff > ../`make -VPKGNAME`.diff .... [NOTE] ==== Se os arquivos foram adicionados, copiados, movidos ou removidos, inclua os comandos man:svn[1]`add`, `copy`, `move` e `remove` que foram usados. O `svn move` ou o `svn copy` deve ser executado antes de aplicar o patch. O `svn add` ou `svn remove` deve ser executado após o patch ser aplicado. ==== Envie o patch seguindo as extref:{problem-reports}[diretrizes de envios de relatórios de problemas, pr-writing]. [[moved-and-updating-files]] == [.filename]#UPDATE# e [.filename]#MOVED# [[moved-and-updating-updating]] === [.filename]#/usr/ports/UPDATING# Se a atualização do port exigir etapas especiais, como alteração de arquivos de configuração ou execução de um programa específico, ela deverá ser documentada neste arquivo. O formato de uma entrada neste arquivo é: [.programlisting] .... YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name Special instructions .... [TIP] ==== Quando incluir instruções exatas para o portmaster, portupgrade e/ou instruções ao pkg, por favor, certifique-se de escapar o shell escaping corretamente. Por exemplo, _não_ use: [source,shell] .... # pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4* .... Como mostrado, o comando só irá funcionar com bourne shells. Em vez disso, use o formato abaixo, que funcionará com ambos bourne shell e c-shell: [source,shell] .... # pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\* .... ==== [NOTE] ==== Recomenda-se que a linha AFFECTS contenha uma glob que corresponda a todos os ports afetados pela entrada, para que as ferramentas automatizadas possam analisá-la com a maior facilidade possível. Se uma atualização diz respeito a todas as versõs do BIND 9 o conteúdo de `AFFECTS` deve ser `usuários do dns/bind9*`, _não deve_ ser `usuários do BIND 9` ==== [[moved-and-updating-moved]] === [.filename]#/usr/ports/MOVED# Este arquivo é usado para listar os ports movidos ou removidos. Cada linha no arquivo é composta por nome do port, para onde o port foi movido, quando e por quê. Se o port foi removido, a seção detalhando onde ele estava pode ser deixado em branco. Cada seção deve ser separada pelo caractere `|` (pipe), assim: [.programlisting] .... old name|new name (blank for deleted)|date of move|reason .... A data deve ser inserida no formato `YYYY-MM-DD`. Novas entradas são adicionadas ao final da lista para mantê-las em ordem cronológica, com a entrada mais antiga no topo da lista. Se um port foi removido, e depois restaurado, exclua a linha neste arquivo que informa que ele foi removido. Se um port foi renomeado e depois renomeado de volta para seu nome original, adicione uma nova entrada com o nome intermediário para o nome antigo e remova a entrada antiga para não criar um loop. [NOTE] ==== Quaisquer alterações devem ser validadas com `Tools/scripts/MOVEDlint.awk`. Se estiver usando um diretório de ports diferente de [.filename]#/usr/ports#, use: [source,shell] .... % cd /home/user/ports % env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk .... ==== diff --git a/documentation/content/pt-br/books/porters-handbook/uses/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/uses/_index.adoc similarity index 96% rename from documentation/content/pt-br/books/porters-handbook/uses/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/uses/_index.adoc index 77d467524f..213fa2acea 100644 --- a/documentation/content/pt-br/books/porters-handbook/uses/chapter.adoc +++ b/documentation/content/pt-br/books/porters-handbook/uses/_index.adoc @@ -1,1682 +1,1681 @@ --- title: Capítulo 17. Using USES Macros prev: books/porters-handbook/keeping-up next: books/porters-handbook/versions --- [[uses]] = Usando Macros `USES` :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 17 :partnums: :source-highlighter: rouge :experimental: :c-plus-plus: c++ :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[uses-intro]] == Uma introdução ao `USES` As macros `USES` facilitam declarar requisitos e configurações de um port. Elas podem adicionar dependências, alterar o comportamento de compilação do port, adicionar metadados a pacotes e assim por diante, tudo selecionando valores simples e predefinidos. Cada seção deste capítulo descreve um possível valor para `USES`, juntamente com seus possíveis argumentos. Argumentos são anexados ao valor após dois pontos (`:`). Vários argumentos são separados por vírgulas (`,`). [[uses-intro-ex1]] .Usando Vários Valores [example] ==== [.programlisting] .... USES= bison perl .... ==== [[uses-intro-ex2]] .Adicionando um Argumento [example] ==== [.programlisting] .... USES= tar:xz .... ==== [[uses-intro-ex3]] .Adicionando Vários Argumentos [example] ==== [.programlisting] .... USES= drupal:7,theme .... ==== [[uses-intro-ex4]] .Entrelaçando Tudo Isso Junto [example] ==== [.programlisting] .... USES= pgsql:9.3+ cpe python:2.7,build .... ==== [[uses-7z]] == `7z` Argumentos possíveis: (none), `p7zip`, `partial` Extrair usando man:7z[1] ao invés de man:bsdtar[1] e definir `EXTRACT_SUFX=.7z`. A opção `p7zip` força uma dependência do `7z` a partir de package:archivers/p7zip[] se aquele do sistema base não for capaz de extrair os arquivos. `EXTRACT_SUFX` não é alterado se a opção `partial` é usada, isso pode ser usado se o arquivo de distribuição principal não tiver extensão [.filename]#.7z#. [[uses-ada]] == `ada` Argumentos possíveis: (none), `5`, `6` Depende de um compilador capaz de usar Ada e define a variável `CC` de acordo. O padrão é usar gcc 5 do ports. Use a opção de versão `:X` para forçar a compilação com uma versão diferente. [[uses-autoreconf]] == `autoreconf` Argumentos possíveis: (none), `build` Execute `autoreconf`. Ele encapsula os comandos `aclocal`, `autoconf`, `autoheader`, `automake`, `autopoint` e `libtoolize`. Cada comando aplica-se a [.filename]#${AUTORECONF_WRKSRC} /configure.ac# ou seu nome antigo [.filename]#${AUTORECONF_WRKSRC}/configure.in#. E se [.filename]#configure.ac# define subdiretórios com seus próprios [.filename]#configure.ac# usando `AC_CONFIG_SUBDIRS`, `autoreconf` irá recursivamente atualizar aqueles também. O argumento `:build` só adiciona dependências de build-time sobre essas ferramentas, mas não executa o `autoreconf`. Um port pode definir `AUTORECONF_WRKSRC` se `WRKSRC` não contiver o caminho para o [.filename]#configure.ac#. [[uses-blaslapack]] == `blaslapack` Argumentos possíveis: (none), `atlas`, `netlib`(padrão), `gotoblas`, `openblas` Adiciona dependências das bibliotecas Blas / Lapack. [[uses-bdb]] == `bdb` Argumentos possíveis: (none), `48`, `5`(padrão), `6` Adiciona uma dependência à biblioteca Berkeley DB. O padrão utiliza package:databases/db5[]. Também pode depender de package:databases/db48[] ao usar o argumento `:48` ou package:databases/db6[] com `:6`. É possível declarar um intervalo de valores aceitáveis, `:48+` procura pela versão maior instalada e utiliza a 4.8 se nenhuma outra estiver instalada. `INVALID_BDB_VER` pode ser usado para especificar versões que não funcionam com este port. O framework expõe as seguintes variáveis ao port: `BDB_LIB_NAME`:: O nome da biblioteca Berkeley DB. Por exemplo, ao usar package:databases/db5[], contém `db-5.3`. `BDB_LIB_CXX_NAME`:: O nome da biblioteca Berkeley DBC++. Por exemplo, ao usar package:databases/db5[], contém `db_cxx-5.3`. `BDB_INCLUDE_DIR`:: A localização do diretório incluso Berkeley DB. Por exemplo, ao usar package:databases/db5[], ele irá conter `${LOCALBASE}/include/db5`. `BDB_LIB_DIR`:: A localização do diretório da biblioteca Berkeley DB. Por exemplo, ao usar package:databases/db5[], contém `${LOCALBASE}/lib`. `BDB_VER`:: A versão detectada de Berkeley DB. Por exemplo, se estiver usando `USES=bdb:48+` e Berkeley DB 5 estiver instalado, irá conter `5`. [IMPORTANT] ==== package:databases/db48[] está obsoleto e não é suportado. Não deve ser usado por nenhum port. ==== [[uses-bison]] == `bison` Argumentos possíveis: (none), `build`, `run`, `both` Utiliza package:devel/bison[] por padrão, sem argumentos ou com o argumento `build`, isso implica que `bison` seja uma dependência de build-time, `run` implica como dependência de run-time e `both` implica em dependências build-time e run-time. [[uses-cabal]] == `cabal` [IMPORTANT] ==== -Não devem ser criados Ports de bibliotecas Haskell, veja <> para maiores informações. +Não devem ser criados Ports de bibliotecas Haskell, veja crossref:special[haskell-libs,Bibliotecas Haskell] para maiores informações. ==== Argumentos possíveis: (none), `hpack` Define valores e targets padrões usados para compilar software Haskell usando o Cabal. Uma dependência de compilação no port do compilador Haskell (GHC) é adicionada. Se o argumento `hpack` for fornecido, uma dependência de compilação do package:devel/hs-hpack[] será adicionada e o `hpack` será chamado na etapa de configuração para gerar o arquivo .cabal. O framework fornece as seguintes variáveis: `USE_CABAL`:: -Se o software usar dependências Haskell, liste-as nesta variável. Cada item deve estar presente no Hackage e ser listado no formato `packagename-_0.1.2_`. As dependências podem ter revisões, especificadas após o símbolo `_`. A geração automática de lista de dependências é suportada, consulte <>. +Se o software usar dependências Haskell, liste-as nesta variável. Cada item deve estar presente no Hackage e ser listado no formato `packagename-_0.1.2_`. As dependências podem ter revisões, especificadas após o símbolo `_`. A geração automática de lista de dependências é suportada, consulte crossref:special[using-cabal,Compilando Aplicações Haskell com `cabal`]. `CABAL_FLAGS`:: Lista de flags a serem passadas para o `cabal-install` durante o estágio de configuração e compilação. As flags são passadas sem alterações (verbatim). `EXECUTABLES`:: Lista de arquivos executáveis instalados pelo port. Valor padrão: `${PORTNAME}`. Os itens desta lista são adicionados automaticamente ao pkg-plist. `SKIP_CABAL_PLIST`:: Se definido, não adicione itens `${EXECUTABLES}` ao pkg-plist. `opt_USE_CABAL`:: Adiciona itens ao `${USE_CABAL}`, dependendo da opção `opt`. `opt_EXECUTABLES`:: Adiciona itens ao `${EXECUTABLES}`, dependendo da opção `opt`. `opt_CABAL_FLAGS`:: Se a opção `opt` estiver ativada, acrescente o valor a `${CABAL_FLAGS}`. Caso contrário, anexe `-value` para desativar a flag. `FOO_DATADIR_VARS`:: Para um executável chamado `FOO`, liste os pacotes Haskell, cujos arquivos de dados devem estar acessíveis pelo executável. [[uses-cargo]] == `cargo` Argumentos possíveis: (none) -Utiliza Cargo para configuração, compilação e testes. Ele pode ser usado para portar aplicativos Rust que usam o sistema de build Cargo. Para obter mais informações, consulte <>. +Utiliza Cargo para configuração, compilação e testes. Ele pode ser usado para portar aplicativos Rust que usam o sistema de build Cargo. Para obter mais informações, consulte crossref:special[using-cargo,Compilando Aplicações Rust com `cargo`].. [[uses-charsetfix]] == `charsetfix` Argumentos possíveis: (none) Previne que o port instale arquivos [.filename]#charset.alias#. Estes arquivos devem ser instalados apenas pelo package:converters/libiconv[]. `CHARSETFIX_MAKEFILEIN` pode ser definido para um caminho relativo ao `WRKSRC` se [.filename]#charset.alias# não for instalado pelo [.filename]#${WRKSRC}/Makefile.in#. [[uses-cmake]] == `cmake` Argumentos possíveis: (none), `env`, `notall`, `noman` Utiliza QMake para configuração e compilação. Por padrão, uma compilação out-of-source é executada, deixando os fontes em `WRKSRC` livres de artefatos de compilação. Com o argumento `insource`, uma compilação in-source será executada. A configuração deste argumento deve ser a exceção quando uma compilação regular out-of-source não funcionar. Por padrão, o argumento Ninja é usado para a compilação. Em alguns casos isso não funciona corretamente. Com o argumento `noninja`, a compilação irá usar o `make` para as compilações. Ele só deve ser usado se uma compilação baseada no Ninja não funcionar. Com o argumento `run`, uma dependência de execução é registrada além de uma dependência de compilação. -Para maiores informações, veja <>. +Para maiores informações, veja crossref:special[using-cmake,Usando o `cmake`]. [[uses-compiler]] == `compiler` Argumentos possíveis: (none), `env` (padrão, implícito) {c-plus-plus}17-lang, {c-plus-plus}14-lang, {c-plus-plus}11-lang, gcc-{c-plus-plus}11-lib, {c-plus-plus}11-lib, {c-plus-plus}0x, c11, openmp, nestedfct, features Determina qual compilador usar com base em qualquer um desejo. Use {c-plus-plus}17-lang se o port precisar de um compilador compatível com {c-plus-plus}17, {c-plus-plus}14-lang se o port precisar de um compilador compatível com {c-plus-plus}14, {c-plus-plus}11-lang se o port precisar de um compilador compatível com {c-plus-plus}11, gcc-{c-plus-plus}11-lib se o port precisar do compilador {gcc-plus-plus} com uma biblioteca {c-plus-plus}11, ou {c-plus-plus}11-lib se o port precisar de uma biblioteca padrão {c-plus-plus}11-ready. Se o port precisar de um compilador que compreenda as funções {c-plus-plus}0X, C11, OpenMP ou funções aninhadas, os parâmetros correspondentes deverão ser usados. Use `features` para solicitar uma lista de recursos suportados pelo compilador padrão. Depois de incluir o arquivo [.filename]#bsd.port.pre.mk# o port pode inspecionar os resultados usando estas variáveis: * `COMPILER_TYPE`: o compilador padrão no sistema, gcc ou clang * `ALT_COMPILER_TYPE`: o compilador alternativo no sistema, gcc ou clang. Apenas definido se dois compiladores estiverem presentes na base do sistema. * `COMPILER_VERSION`: os dois primeiros dígitos da versão do compilador padrão. * `ALT_COMPILER_VERSION`: os dois primeiros dígitos da versão do compilador alternativo, se presente. * `CHOSEN_COMPILER_TYPE`: o compilador escolhido, gcc ou clang * `COMPILER_FEATURES`: os recursos suportados pelo compilador padrão. Atualmente lista a biblioteca C++. [[uses-cpe]] == `cpe` Argumentos possíveis: (none) Inclui informações da Common Platform Enumeration (CPE) no manifesto do pacote como uma string CPE 2.3 formatada. Veja as http://scap.nist.gov/specifications/cpe/[especificações CPE] para mais detalhes. Para adicionar informações de CPE a um port, siga estas etapas: [.procedure] ==== . Procure pelo registro oficial CPE para o produto de software, usando o http://web.nvd.nist.gov/view/cpe/search[mecanismo de pesquisa CPE] do NVD ou no http://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml[dicionário oficial CPE] (aviso, o arquivo XML é muito grande). _Nunca crie os dados da CPE._ . Adicione `cpe` na variável `USES` e compare o resultado de `make -V CPE_STR` com o registro no dicionário CPE. Continue com um passo de cada vez até `make -V CPE_STR` ficar correto. . Se o nome do produto (segundo campo, com o valor padrão para `PORTNAME`) estiver incorreto, defina `CPE_PRODUCT`. . Se o nome do fornecedor (primeiro campo, com o valor padrão para `CPE_PRODUCT`) estiver incorreto, defina `CPE_VENDOR`. . Se o campo de versão (terceiro campo, com o valor padrão para `PORTVERSION`) estiver incorreto, defina `CPE_VERSION`. . Se o campo de atualização (quarto campo, valor padrão vazio) estiver incorreto, defina `CPE_UPDATE`. . Se ainda não estiver correto, verifique o arquivo [.filename]#Mk/Uses/cpe.mk# para detalhes adicionais, ou entre em contato com o Ports Security Team mailto:ports-secteam@FreeBSD.org[ports-secteam@FreeBSD.org]. . Derive o máximo possível do nome CPE a partir de variáveis ​​existentes, tal como as variáveis `PORTNAME` e `PORTVERSION`. Use modificadores de variáveis ​​para extrair as partes relevantes delas, em vez de colocar o nome direto no código. . _Sempre_ execute `make -V CPE_STR` e verifique a saída antes de fazer o commit de qualquer coisa que mude o `PORTNAME` ou `PORTVERSION` ou qualquer outra variável que é usada para derivar a variável `CPE_STR`. ==== [[uses-cran]] == `cran` Argumentos possíveis: (none), `auto-plist`, `compiles` Utiliza a Comprehensive R Archive Network. Especifique `auto-plist` para gerar automaticamente o arquivo [.filename]#pkg-plist#. Especifique `compiles` se o port tiver código que precise ser compilado. [[uses-desktop-file-utils]] == `desktop-file-utils` Argumentos possíveis: (none) Utiliza update-desktop-database a partir de package:devel/desktop-file-utils[]. Uma etapa extra de post-install será executada sem interferir em nenhuma etapa de post-install que já esteja no [.filename]#Makefile# do port. Uma linha com <> será adicionada ao plist. [[uses-desthack]] == `desthack` Argumentos possíveis: (none) Altera o comportamento do GNU configure para suportar corretamente a variável `DESTDIR` no caso do software original não suportar. [[uses-display]] == `display` Argumentos possíveis: (none), _ARGS_ Define um display environment virtual. Se a variável de ambiente `DISPLAY` não estiver definida, então Xvfb é adicionado como uma dependência de compilação e a variável `CONFIGURE_ENV` é estendida com o número do port da instância do Xvfb em execução no momento. O parâmetro _ARGS_ é definido como `install` por padrão e controla a fase na qual se inicia e para a exibição virtual. [[uses-dos2unix]] == `dos2unix` Argumentos possíveis: (none) -O port tem arquivos com terminações de linha no formato do DOS que precisam ser convertidos. Inúmeras variáveis ​​podem ser definidas para controlar quais arquivos serão convertidos. O padrão é converter _todos_ arquivos, incluindo binários. Veja <> para exemplos. +O port tem arquivos com terminações de linha no formato do DOS que precisam ser convertidos. Inúmeras variáveis ​​podem ser definidas para controlar quais arquivos serão convertidos. O padrão é converter _todos_ arquivos, incluindo binários. Veja crossref:slow-porting[slow-patch-automatic-replacements,Substituições Automáticas Simples] para exemplos. * `DOS2UNIX_REGEX`: casa nomes de arquivos com base em uma expressão regular. * `DOS2UNIX_FILES`: casa com nomes de arquivos literais. * `DOS2UNIX_GLOB`: casa com nomes de arquivos baseados em um padrão glob. * `DOS2UNX_WRKSRC`: o diretório onde iniciar as conversões. O padrão é `${WRKSRC}`. [[uses-drupal]] == `drupal` Argumentos possíveis: `7`, `module`, `theme` Automatiza a instalação de um port que é um tema ou módulo Drupal. Use com a versão Drupal que o port está esperando. Por exemplo, `USES=drupal:7,module` diz que este port cria um módulo do Drupal 6. Um tema do Drupal 7 pode ser especificado com `USES=drupal:7,theme`. [[uses-fakeroot]] == `fakeroot` Argumentos possíveis: (none) Altera alguns comportamentos padrão dos sistemas de compilação para permitir instalar como um usuário normal. Veja https://wiki.debian.org/FakeRoot[] para mais informações sobre `fakeroot`. [[uses-fam]] == `fam` Argumentos possíveis: (none), `fam`, `gamin` Usa um File Alteration Monitor como uma dependência de biblioteca, package:devel/fam[] ou package:devel/gamin[]. Usuários finais podem definir WITH_FAM_SYSTEM para especificar sua preferência. [[uses-firebird]] == `firebird` Argumentos possíveis: (none), `25` Adiciona uma dependência da biblioteca client do banco de dados do Firebird. [[uses-fonts]] == `fonts` Argumentos possíveis: (none), `fc`, `fcfontsdir`(padrão), `fontsdir`, `none` Adiciona uma dependência de tempo de execução nas ferramentas necessárias para registrar fontes. Dependendo do argumento, adiciona entradas para o plist `<> ${FONTSDIR}`, `<> ${FONTSDIR}`, `<> ${FONTSDIR}`, ou nenhuma entrada se o argumento for `none`. Valor padrão de `FONTSDIR` é [.filename]#${PREFIX}/shared/fonts/${FONTNAME}# e `FONTNAME` é `${PORTNAME}`. Adiciona `FONTSDIR` para `PLIST_SUB` e `SUB_LIST` [[uses-fortran]] == `fortran` Argumentos possíveis: `gcc` (padrão) Usa o compilador GNU Fortran. [[uses-fuse]] == `fuse` Argumentos possíveis: `2` (padrão), `3` O port irá depender da biblioteca FUSE e irá manipular a dependência do módulo do kernel dependendo da versão do FreeBSD. [[uses-gem]] == `gem` Argumentos possíveis: (none), `noautoplist` Manipula a compilação com RubyGems. Se `noautoplist` for usado, a lista de empacotameno não será gerada automaticamente. [[uses-gettext]] == `gettext` Argumentos possíveis: (none) Descontinuado. Incluirá ambos <> e <>. [[uses-gettext-runtime]] == `gettext-runtime` Argumentos possíveis: (none), `lib` (padrão),`build`, `run` Utiliza package:devel/gettext-runtime[]. Por padrão, sem argumentos ou com o argumento `lib`, implica uma dependência da biblioteca [.filename]#libintl.so#. `build` e `run` implicam, respectivamente, uma dependência de [.filename]#gettext# em build-time e run-time. [[uses-gettext-tools]] == `gettext-tools` Argumentos possíveis: (none), `build` (padrão),`run` Utiliza package:devel/gettext-tools[]. Por padrão, sem argumento ou com o argumento `build`, uma dependência de [.filename]#msgfmt# em build-time é registrada. Com o argumento `run`, uma dependência em run-time é registrada. [[uses-ghostscript]] == `ghostscript` Argumentos possíveis: _X_, `build`, `run`, `nox11` Uma versão _X_ específica pode ser usada. Versões possíveis são `7`, `8`, `9` e `agpl` (padrão). `nox11` indica que a versão `-nox11` do port é necessária. `build` e `run` adicionam dependências de Ghostscript em build-time e run-time. O padrão é ambas as dependências, build-time e run-time. [[uses-gl]] == `gl` Argumentos possíveis: (none) Fornece uma maneira fácil para depender dos componentes GL. Os componentes devem ser listados na variável `USE_GL`. Os componentes disponíveis são: `egl`:: adiciona uma dependência de biblioteca [.filename]#libEGL.so# de package:graphics/libglvnd[] `gbm`:: Adiciona uma dependência de biblioteca [.filename]#libgbm.so# de package:graphics/mesa-libs[] `gl`:: Adiciona uma dependência de biblioteca [.filename]#libGL.so# de package:graphics/libglvnd[] `glesv2`:: Adiciona uma dependência de biblioteca [.filename]#libGLESv2.so# de package:graphics/libglvnd[] `glew`:: Adiciona uma dependência de biblioteca [.filename]#libGLEW.so# de package:graphics/glew[] `glu`:: Adiciona uma dependência de biblioteca [.filename]#libGLU.so# de package:graphics/libGLU[] `glut`:: Adiciona uma dependência de biblioteca [.filename]#libglut.so# de package:graphics/freeglut[] `opengl`:: Adiciona uma dependência de biblioteca [.filename]#libOpenGL.so# de package:graphics/libglvnd[] [[uses-gmake]] == `gmake` Argumentos possíveis: (none) Utiliza package:devel/gmake[] como uma dependência em run-time e configura o ambiente para usar `gmake` como `make` padrão para a compilação. [[uses-gnome]] == `gnome` Argumentos possíveis: (none) Fornece uma maneira fácil para depender dos componentes do GNOME. Os componentes devem ser listados na variável `USE_GNOME`. Os componentes disponíveis são: * `atk` * `atkmm` * `cairo` * `cairomm` * `dconf` * `esound` * `evolutiondataserver3` * `gconf2` * `gconfmm26` * `gdkpixbuf` * `gdkpixbuf2` * `glib12` * `glib20` * `glibmm` * `gnomecontrolcenter3` * `gnomedesktop3` * `gnomedocutils` * `gnomemenus3` * `gnomemimedata` * `gnomeprefix` * `gnomesharp20` * `gnomevfs2` * `gsound` * `gtk-update-icon-cache` * `gtk12` * `gtk20` * `gtk30` * `gtkhtml3` * `gtkhtml4` * `gtkmm20` * `gtkmm24` * `gtkmm30` * `gtksharp20` * `gtksourceview` * `gtksourceview2` * `gtksourceview3` * `gtksourceviewmm3` * `gvfs` * `intlhack` * `intltool` * `introspection` * `libartlgpl2` * `libbonobo` * `libbonoboui` * `libgda5` * `libgda5-ui` * `libgdamm5` * `libglade2` * `libgnome` * `libgnomecanvas` * `libgnomekbd` * `libgnomeprint` * `libgnomeprintui` * `libgnomeui` * `libgsf` * `libgtkhtml` * `libgtksourceviewmm` * `libidl` * `librsvg2` * `libsigc++12` * `libsigc++20` * `libwnck` * `libwnck3` * `libxml++26` * `libxml2` * `libxslt` * `metacity` * `nautilus3` * `orbit2` * `pango` * `pangomm` * `pangox-compat` * `py3gobject3` * `pygnome2` * `pygobject` * `pygobject3` * `pygtk2` * `pygtksourceview` * `referencehack` * `vte` * `vte3` A dependência padrão é em built-time e run-time, pode ser alterada com `:build` ou `:run`. Por exemplo: [.programlisting] .... USES= gnome USE_GNOME= gnomemenus3:build intlhack .... -Veja <> para maiores informações. +Veja crossref:special[using-gnome,Usando o GNOME] para maiores informações. [[uses-go]] == `go` [IMPORTANT] ==== -Não devem ser criados Ports de bibliotecas Go, veja <> para maiores informações. +Não devem ser criados Ports de bibliotecas Go, veja crossref:special[go-libs,Bibliotecas Go] para maiores informações. ==== Argumentos possíveis: (none), `modules`, `no_targets`, `run` Define valores e targets padrão usados para compilar aplicações Go. Uma dependência de compilação no port do compilador Go selecionada via `GO_PORT` é adicionada. Por padrão, a compilação é executada no modo GOPATH. Se o software Go usar módulos, o modo de reconhecimento de módulos pode ser ativado com o argumento `modules`. `no_targets` irá configurar o ambiente de compilação com `GO_ENV`, `GO_BUILDFLAGS` mas irá pular os targets `post-extract` e `do-{build,install,test}`. `run` também adicionará uma dependência de tempo de execução do que estiver em `GO_PORT`. O processo de compilação é controlado por várias variáveis: `GO_PKGNAME`:: O nome do pacote Go ao compilar no modo GOPATH. Este é o diretório que será criado em `${GOPATH}/src`. Se não estiver definido explicitamente e `GH_SUBDIR` ou `GL_SUBDIR` estiverem presente, o valor `GO_PKGNAME` será inferido deles. Isso não é necessário quando compilado no modo de reconhecimento de módulos. `GO_TARGET`:: Os pacotes a serem compilados. O valor padrão é `${GO_PKGNAME}`. `GO_TARGET` também pode ser uma tupla na forma `package:path` onde path pode ser um nome de arquivo simples ou um caminho completo começando com `${PREFIX}`. `GO_TESTTARGET`:: Os pacotes para testar. O valor padrão é `./...` (o pacote atual e todos os subpacotes). `CGO_CFLAGS`:: Valores adicionais da variável `CFLAGS` a serem passados ​​para o compilador C pelo `Go`. `CGO_LDFLAGS`:: Valores adicionais da variável `LDFLAGS` a serem passados ​​para o compilador C pelo `Go`. `GO_BUILDFLAGS`:: Argumentos de compilação adicionais para passar para o `go build`. `GO_TESTFLAGS`:: Argumentos de compilação adicionais para passar para o `go test`. `GO_PORT`:: O port do compilador Go a ser utilizado. Por padrão é package:lang/go[] mas pode ser definido para package:lang/go-devel[] no `make.conf` para testes de futuras versões Go. + [WARNING] ==== - Esta variável não deve ser definida por ports individuais! ==== -Ver <> para exemplos de uso. +Ver crossref:special[using-go,Compilando Aplicações Go] para exemplos de uso. [[uses-gperf]] == `gperf` Argumentos possíveis: (none) Adiciona uma dependência package:devel/gperf[] em buildtime se `gperf` não estiver presente no sistema base. [[uses-grantlee]] == `grantlee` Argumentos possíveis: `5`, `selfbuild` Manipula a dependência em Grantlee. Especifique `5` para depender da versão baseada no Qt5, package:devel/grantlee5[]. `selfbuild` é usado internamente pelo package:devel/grantlee5[] para obter os números de suas versões. [[uses-groff]] == `groff` Argumentos possíveis: `build`, `run`, `both` Registra uma dependência de package:textproc/groff[] se não estiver presente no sistema base. [[uses-gssapi]] == `gssapi` Argumentos possíveis: (none), `base` (padrão), `heimdal`, `mit`, `flags`, `bootstrap` Manipular as dependências necessárias para os consumers do GSS-API. Apenas as bibliotecas que fornecem os mecanismos do Kerberos estão disponíveis. Por padrão, ou definido como `base`, a biblioteca GSS-API do sistema base é usada. Também pode ser definido para `heimdal` para usar package:security/heimdal[] ou `mit` para usar package:security/krb5[]. Quando a instalação local do Kerberos não está em `LOCALBASE` defina a variável `HEIMDAL_HOME` (para `heimdal`) ou a variável `KRB5_HOME` (para `krb5`) para a instalação local do Kerberos. Essas variáveis ​​são exportadas para os ports para serem usadas: * `GSSAPIBASEDIR` * `GSSAPICPPFLAGS` * `GSSAPIINCDIR` * `GSSAPILDFLAGS` * `GSSAPILIBDIR` * `GSSAPILIBS` * `GSSAPI_CONFIGURE_ARGS` As opções de `flags` podem estar lado a lado com `base`, `heimdal` ou `mit` para adicionar automaticamente `GSSAPICPPFLAGS`, `GSSAPILDFLAGS` e `GSSAPILIBS` para `CFLAGS`, `LDFLAGS` e `LDADD`, respectivamente. Por exemplo, use `base,flags`. A opção `bootstrap` é um prefixo especial apenas para o uso do package:security/krb5[] e package:security/heimdal[]. Por exemplo, use `bootstrap,mit`. [[uses-gssapi-ex1]] .Uso Típico [example] ==== [.programlisting] .... OPTIONS_SINGLE= GSSAPI OPTIONS_SINGLE_GSSAPI= GSSAPI_BASE GSSAPI_HEIMDAL GSSAPI_MIT GSSAPI_NONE GSSAPI_BASE_USES= gssapi GSSAPI_BASE_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_HEIMDAL_USES= gssapi:heimdal GSSAPI_HEIMDAL_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_MIT_USES= gssapi:mit GSSAPI_MIT_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_NONE_CONFIGURE_ON= --without-gssapi .... ==== [[uses-horde]] == `horde` Argumentos possíveis: (none) -Adicionar dependências de builtime e runtime em package:devel/pear-channel-horde[]. Outras dependências Horde podem ser adicionadas com `USE_HORDE_BUILD` e `USE_HORDE_RUN`. Veja <> para maiores informações. +Adicionar dependências de builtime e runtime em package:devel/pear-channel-horde[]. Outras dependências Horde podem ser adicionadas com `USE_HORDE_BUILD` e `USE_HORDE_RUN`. Veja crossref:special[php-horde,Módulos Horde] para maiores informações. [[uses-iconv]] == `iconv` Argumentos possíveis: (none), `lib`, `build`, `patch`, `translit`, `wchar_t` -Utilização de funções `iconv`, seja do port package:converters/libiconv[] como uma dependência de buil-time e run-time, ou do sistema base em um 10-CURRENT após um `iconv` nativo ser comitado em link:https://svnweb.freebsd.org/changeset/base/254273[r254273]. Por padrão, sem argumentos ou com o argumento `lib`, implica em `iconv` com dependências de build-time e run-time. `build` implica uma dependência de build-time e `patch` implica uma dependência de patch-time. Se o port usa extensões iconv `WCHAR_T` ou `//TRANSLIT` , adicione os argumentos relevantes para que o iconv correto seja usado. Para mais informações, veja <>. +Utilização de funções `iconv`, seja do port package:converters/libiconv[] como uma dependência de buil-time e run-time, ou do sistema base em um 10-CURRENT após um `iconv` nativo ser comitado em link:https://svnweb.freebsd.org/changeset/base/254273[r254273]. Por padrão, sem argumentos ou com o argumento `lib`, implica em `iconv` com dependências de build-time e run-time. `build` implica uma dependência de build-time e `patch` implica uma dependência de patch-time. Se o port usa extensões iconv `WCHAR_T` ou `//TRANSLIT` , adicione os argumentos relevantes para que o iconv correto seja usado. Para mais informações, veja crossref:special[using-iconv,Usando `iconv`]. [[uses-imake]] == `imake` Argumentos possíveis: (none), `env`, `notall`, `noman` Adiciona package:devel/imake[] como uma dependência de built-time e executa `xmkmf -a` durante o estágio `configure`. Se o argumento `env` é passado, o target `configure` não é definido. Se a flag `-a` for um problema para o port, adicione o argumento `notall`. E se `xmkmf` não gerar um target `install.man`, adicione o argumento `noman`. [[uses-kde]] == `kde` Argumentos possíveis: `5` -Adiciona dependência de componentes KDE. Veja <> para maiores informações. +Adiciona dependência de componentes KDE. Veja crossref:special[using-kde,Usando o KDE] para maiores informações. [[uses-kmod]] == `kmod` Argumentos possíveis: (none), `debug` Preenche o boilerplate para os ports de módulo do kernel, atualmente: * Adiciona `kld` em `CATEGORIES`. * Define `SSP_UNSAFE`. * Defina `IGNORE` se as fontes do kernel não forem encontradas em `SRC_BASE`. * Define `KMODDIR` para [.filename]#/boot/modules# por padrão, adiciona isso para a variável `PLIST_SUB` e `MAKE_ENV`, e o cria após a instalação. Se a variável `KMODDIR` está definida para o [.filename]#/boot/kernel#, ela será reescrita para [.filename]#/boot/modules#. Isso evita quebrar pacotes ao atualizar o kernel devido ao [.filename]#/boot/kernel# ser renomeado para [.filename]#/boot/kernel.old# no processo. * Manipula módulos cross-referencing do kernel acerca da instalação e desinstalação, usando <>. * Se o argumento `debug` é passado, o port pode instalar uma versão de debug do módulo no arquivo [.filename]#KERN_DEBUGDIR#/[.filename]#KMODDIR#. Por padrão, a variável `KERN_DEBUGDIR` é copiada da `DEBUGDIR` e definido para [.filename]#/usr/lib/debug#. O framework irá cuidar da criação e remoção de quaisquer diretórios necessários. [[uses-lha]] == `lha` Argumentos possíveis: (none) Define `EXTRACT_SUFX` para `.lzh` [[uses-libarchive]] == `libarchive` Argumentos possíveis: (none) Registra uma dependência de package:archivers/libarchive[]. Quaisquer ports dependendo de libarchive deve incluir `USES=libarchive`. [[uses-libedit]] == `libedit` Argumentos possíveis: (none) Registra uma dependência de package:devel/libedit[]. Quaisquer ports dependendo de libedit devem incluir `USES=libedit`. [[uses-libtool]] == `libtool` Argumentos possíveis: (none), `keepla`, `build` Scripts `libtool` de patches. Isso deve ser adicionado a todos os ports que usam `libtool`. O argumento `keepla` pode ser usado para manter arquivos [.filename]#.la#. Alguns ports não vêm com sua própria cópia da libtool e precisam de uma dependência de package:devel/libtool[] em build time, use o argumento `:build` para adicionar essa dependência. [[uses-linux]] == `linux` Argumentos possíveis: `c6`, `c7` Framework de compatibilidade de ports com Linux. Especifique `c6` para depender de pacotes do CentOS 6. Especifique `c7` para depender de pacotes do CentOS 7. Os pacotes disponíveis são: * `allegro` * `alsa-plugins-oss` * `alsa-plugins-pulseaudio` * `alsalib` * `atk` * `avahi-libs` * `base` * `cairo` * `cups-libs` * `curl` * `cyrus-sasl2` * `dbusglib` * `dbuslibs` * `devtools` * `dri` * `expat` * `flac` * `fontconfig` * `gdkpixbuf2` * `gnutls` * `graphite2` * `gtk2` * `harfbuzz` * `jasper` * `jbigkit` * `jpeg` * `libasyncns` * `libaudiofile` * `libelf` * `libgcrypt` * `libgfortran` * `libgpg-error` * `libmng` * `libogg` * `libpciaccess` * `libsndfile` * `libsoup` * `libssh2` * `libtasn1` * `libthai` * `libtheora` * `libv4l` * `libvorbis` * `libxml2` * `mikmod` * `naslibs` * `ncurses-base` * `nspr` * `nss` * `openal` * `openal-soft` * `openldap` * `openmotif` * `openssl` * `pango` * `pixman` * `png` * `pulseaudio-libs` * `qt` * `qt-x11` * `qtwebkit` * `scimlibs` * `sdl12` * `sdlimage` * `sdlmixer` * `sqlite3` * `tcl85` * `tcp_wrappers-libs` * `tiff` * `tk85` * `ucl` * `xorglibs` [[uses-localbase]] == `localbase` Argumentos possíveis: (none), `ldflags` Garante que as bibliotecas de dependências em `LOCALBASE` sejam usadas ​​em vez das do sistema base. Especifique `ldflags` para adicionar `-L${LOCALBASE}/lib` para a variável `LDFLAGS` ao invés de `LIBS`. Ports que dependem de bibliotecas que também estão presentes no sistema base devem usar isso. Também é usado internamente por algumas outras variáveis `USES`. [[uses-lua]] == `lua` Argumentos possíveis: (none), `_XY_`, `_XY_+`, `-_XY_`, `_XY_-_ZA_`, `module`, `flavors`, `build`, `run`, `env` Adiciona uma dependência de Lua. Por padrão, esta é uma dependência de biblioteca, a menos que seja invalidado por uma opção `build` ou `run`. A opção `env` evita a adição de qualquer dependência, enquanto ainda define todas as variáveis usuais. A versão padrão é definida pelo mecanismo usual `DEFAULT_VERSIONS`, a menos que uma versão ou intervalo de versões seja especificado como um argumento, por exemplo, `51` or `51-53`. Os aplicativos que usam Lua são normalmente compilados para apenas uma única versão do Lua. No entanto, os módulos de biblioteca destinados a serem carregados pelo código Lua devem usar a opção `module` para compilar com vários flavors. -Para maiores informações, veja <>. +Para maiores informações, veja crossref:special[using-lua,Usando Lua]. [[uses-lxqt]] == `lxqt` Argumentos possíveis: (none) -Manipular dependências para o LXQt Desktop Environment. Use a variável `USE_LXQT` para selecionar os componentes necessários para o port. Veja <> para maiores informações. +Manipular dependências para o LXQt Desktop Environment. Use a variável `USE_LXQT` para selecionar os componentes necessários para o port. Veja crossref:special[using-lxqt,Usando o LXQt] para maiores informações. [[uses-makeinfo]] == `makeinfo` Argumentos possíveis: (none) Adiciona uma dependência de build-time em `makeinfo` se o mesmo não estiver presente no sistema base. [[uses-makeself]] == `makeself` Argumentos possíveis: (none) Indica que os arquivos de distribuição são archives makeself e define as dependências apropriadas. [[uses-mate]] == `mate` Argumentos possíveis: (none) Fornece uma maneira fácil para depender de componentes do MATE. Os componentes devem ser listados em `USE_MATE`. Os componentes disponíveis são: * `autogen` * `caja` * `common` * `controlcenter` * `desktop` * `dialogs` * `docutils` * `icontheme` * `intlhack` * `intltool` * `libmatekbd` * `libmateweather` * `marco` * `menus` * `notificationdaemon` * `panel` * `pluma` * `polkit` * `session` * `settingsdaemon` A dependência padrão é em built-time e run-time, pode ser alterada com `:build` ou `:run`. Por exemplo: [.programlisting] .... USES= mate USE_MATE= menus:build intlhack .... [[uses-meson]] == `meson` Argumentos possíveis: (none) -Fornece suporte para projetos baseados no Meson. Para maiores informações, consulte <>. +Fornece suporte para projetos baseados no Meson. Para maiores informações, consulte crossref:special[using-meson,Usando `meson`]. [[uses-metaport]] == `metaport` Argumentos possíveis: (none) Define as seguintes variáveis ​​para facilitar a criação de um metaport: `MASTER_SITES`, `DISTFILES`, `EXTRACT_ONLY`, `NO_BUILD`, `NO_INSTALL`, `NO_MTREE`, `NO_ARCH`. [[uses-mysql]] == `mysql` Argumentos possíveis: (none), `_version_`, `client` (padrão), `server`, `embedded` Fornece suporte para o MySQL. Se nenhuma versão for informada, tenta encontrar a versão atual instalada. Fall back para a versão padrão, MySQL-5.6. As possíveis versões são `55`, `55m`, `55p`, `56`, `56p`, `56w`, `57`, `57p`, `80`, `100m`, `101m` e `102m`. Os sufixos `m` e `p` são para MariaDB e Percona, variantes do MySQL. `server` e `embbeded` adicionam uma dependência de build- e run-time do servidor MySQL. Ao usar `server` ou `embbeded`, é adicionado `client` para também adicionar uma dependência no arquivo [.filename]#libmysqlclient.so#. Um port pode definir `IGNORE_WITH_MYSQL` se algumas versões não forem suportadas. O framework define a variável `MYSQL_VER` para a versão detectada do MySQL. [[uses-mono]] == `mono` Argumentos possíveis: (none), `nuget` Adiciona uma dependência no framework Mono (atualmente apenas C#) definindo as dependências apropriadas. Especifique `nuget` quando o port usa pacotes nuget. `NUGET_DEPENDS` precisa ser definido com os nomes e versões dos pacotes nuget no formato `_name_=_version_`. Uma pacote de origem opcional pode ser adicionado usando `name=version:origin`. O target auxiliar, `buildnuget`, exibirá o conteúdo da variável `NUGET_DEPENDS` com base no arquivo [.filename]#packages.config# fornecido. [[uses-motif]] == `motif` Argumentos possíveis: (none) Utiliza package:x11-toolkits/open-motif[] como uma dependência de biblioteca. Os usuários finais podem definir `WANT_LESSTIF` para a dependência estar em package:x11-toolkits/lesstif[] ao invés de package:x11-toolkits/open-motif[]. [[uses-ncurses]] == `ncurses` Argumentos possíveis: (none), `base`, `port` Utiliza ncurses, e faz com que algumas variáveis ​​úteis sejam definidas. [[uses-ninja]] == `ninja` Argumentos possíveis: (none) Utiliza ninja para compilar o port. [[uses-objc]] == `objc` Argumentos possíveis: (none) Adiciona dependências de objetive C (compilador, biblioteca de runtime) se o sistema base não suportar isto. [[uses-openal]] == `openal` Argumentos possíveis: `al`, `soft` (padrão), `yes`, `alut` Utiliza OpenAL. O backend pode ser especificado, com a implementação do software como padrão. O usuário pode especificar um backend preferido com `WANT_OPENAL`. Os valores válidos para este manipulador são `soft` (padrão) e `si`. [[uses-pathfix]] == `pathfix` Argumentos possíveis: (none) Procura pelos arquivos [.filename]#Makefile.in# e [.filename]#configure# na variável `PATHFIX_WRKSRC` (padrão é `WRKSRC`) e corrige os caminhos comuns para garantir que eles respeitem a hierarquia do FreeBSD. Por exemplo, ele corrige o diretório de instalação dos arquivos [.filename]#.pc# do `pkgconfig` para [.filename]#${PREFIX}/libdata/pkgconfig#. Se o port usa `USES=autoreconf`, [.filename]#Makefile.am# será adicionado automaticamente a `PATHFIX_MAKEFILEIN`. Se o port tem definido <> ele vai procurar pelo arquivo [.filename]#CMakeLists.txt# dentro da variável `PATHFIX_WRKSRC`. Se necessário, esse nome de arquivo padrão pode ser alterado com `PATHFIX_CMAKELISTSTXT`. [[uses-pear]] == `pear` Argumentos possíveis: `env` -Adiciona uma dependência do package:devel/pear[]. Ele irá configurar o comportamento padrão do software usando o Repositório de Extensão e Aplicativos do PHP. O uso do argumento `env` apenas configura as variáveis de ambiente PEAR. Veja <> para maiores informações. +Adiciona uma dependência do package:devel/pear[]. Ele irá configurar o comportamento padrão do software usando o Repositório de Extensão e Aplicativos do PHP. O uso do argumento `env` apenas configura as variáveis de ambiente PEAR. Veja crossref:special[php-pear,Módulos PEAR] para maiores informações. [[uses-perl5]] == `perl5` Argumentos possíveis: (none) Depende do Perl. A configuração é feita usando a variável `USE_PERL5`. `USE_PERL5` pode conter as fases que precisam usar Perl, pode ser `extract`, `patch`, `build`, `run` ou `test`. `USE_PERL5` também pode conter `configure`, `modbuild` ou `modbuildtiny` quando [.filename]#Makefile.PL#, [.filename]#Build.PL# ou Módulo::Build::Tiny's, flavor de [.filename]#Build.PL# é necessário. O padrão de `USE_PERL5` é `build run`. Ao usar `configure`, `modbuild` ou `modbuildtiny`, uso de `build` e `run` são implícitos. -Veja <> para maiores informações. +Veja crossref:special[using-perl,Usando Perl] para maiores informações. [[uses-pgsql]] == `pgsql` Argumentos possíveis: (none), `_X.Y_`, `_X.Y_+`, `_X.Y_-`, `_X.Y_-_Z.A_` Fornece suporte para o PostgreSQL. O mantenedor do port pode definir a versão requisitada. Podem ser especificadas versões mínima e máxima ou um intervalo; por exemplo, `9.0-`, `8.4+`, `8.4-9.2.` Por padrão, a dependência adicionada será o cliente, mas se o port exigir componentes adicionais, isso poderá ser feito usando `WANT_PGSQL=_component[:target]_`; por exemplo, `WANT_PGSQL=server:configure pltcl plperl`. Os componentes disponíveis são: * `client` * `contrib` * `docs` * `pgtcl` * `plperl` * `plpython` * `pltcl` * `server` [[uses-php]] == `php` Argumentos possíveis: (none), `phpize`, `ext`, `zend`, `build`, `cli`, `cgi`, `mod`, `web`, `embed`, `pecl`, `flavors`, `noflavors` Fornece suporte para o PHP. Adiciona uma dependência de run-time na versão padrão do PHP, package:lang/php56[]. `phpize`:: Utilizado para compilar uma extensão do PHP. Habilita flavors. `ext`:: Usado para compilar, instalar e registrar uma extensão do PHP. Habilita flavors. `zend`:: Usado para criar, instalar e registrar uma extensão do Zend. Habilita flavors. `build`:: Define PHP também como uma dependência de build-time. `cli`:: Precisa da versão CLI do PHP. `cgi`:: Precisa da versão CGI do PHP. `mod`:: Precisa do módulo Apache para o PHP. `web`:: Precisa do módulo Apache ou a versão CGI do PHP. `embed`:: Precisa da versão da biblioteca embarcada do PHP. `pecl`:: Fornece padrões para baixar extensões PHP do repositório PECL. Habilita flavors. `flavors`:: Habilita a geração de <> automático. Flavors serão gerados para todas as versões do PHP, exceto as presentes na variável <>. `noflavors`:: Desativa a geração automática de flavors do PHP. _Deve apenas_ ser usado com extensões fornecidas pelo próprio PHP. Variáveis ​​são usadas para especificar quais módulos PHP são necessários, bem como qual versão do PHP são suportadas. `USE_PHP`:: A lista das extensões PHP requisitadas em run-time. Adicione `:build` ao nome da extensão para adicionar uma dependência em build-time. Exemplo: `pcre xml:build gettext` [[uses-php-ignore]] `IGNORE_WITH_PHP`:: O port não funciona com a versão do PHP fornecida. Para possíveis valores, observe o conteúdo da variável `_ALL_PHP_VERSIONS` no arquivo [.filename]#Mk/Uses/php.mk#. Ao compilar uma extensão do PHP ou Zend com `:ext` ou `:zend`, estas variáveis ​​podem ser definidas: `PHP_MODNAME`:: O nome da extensão do PHP ou Zend. O valor padrão é `${PORTNAME}`. `PHP_HEADER_DIRS`:: Uma lista de subdiretórios dos quais instalar arquivos header. O framework sempre irá instalar os arquivos header que estão presentes no mesmo diretório que a extensão. `PHP_MOD_PRIO`:: A prioridade na qual carregar a extensão. É um número entre `00` e `99`. + Para extensões que não dependem de nenhuma extensão, a prioridade é definida automaticamente como `20`, para extensões que dependem de outra extensão, a prioridade é definida automaticamente como `30`. Algumas extensões podem precisar ser carregadas antes de todas as outras extensões, por exemplo package:www/php56-opcache[]. Algumas podem precisar ser carregadas após uma extensão com prioridade de `30`. Nesse caso, adicione `PHP_MOD_PRIO=_XX_` no Makefile do port. Por exemplo: + [.programlisting] .... USES= php:ext USE_PHP= wddx PHP_MOD_PRIO= 40 .... Estas variáveis ​​estão disponíveis para uso em `PKGNAMEPREFIX` ou `PKGNAMESUFFIX`: `PHP_PKGNAMEPREFIX`:: Contém `php__XY__-` onde _XY_ é a versão do PHP atual. Use com módulos e extensões PHP. `PHP_PKGNAMESUFFIX`:: Contém `-php__XY__` onde _XY_ é a versão do PHP atual do flavor. Use com aplicativos PHP. `PECL_PKGNAMEPREFIX`:: Contém `php__XY__-pecl` onde _XY_ é a versão atual do PHP do flavor. Usar com módulos PECL. [IMPORTANT] ==== Com flavors, todas as extensões PHP, extensões PECL, módulos PEAR _devem ter_ um nome de pacote diferente, então todos devem usar uma dessas três variáveis ​​em suas variáveis `PKGNAMEPREFIX` ou `PKGNAMESUFFIX`. ==== [[uses-pkgconfig]] == `pkgconfig` Argumentos possíveis: (none), `build` (padrão), `run`, `both` Utiliza package:devel/pkgconf[]. Sem argumentos ou com o argumento `build`, implica em `pkg-config` como uma dependência de build-time. `run` implica em uma dependência em run-time e `both` implica em dependências de run-time e build-time. [[uses-pure]] == `pure` Argumentos possíveis: (none), `ffi` Utiliza package:lang/pure[]. Usado largamente para build relacionado com ports pure. Com o argumento `ffi`, isso implica em package:devel/pure-ffi[] como uma dependência em run-time. [[uses-pyqt]] == `pyqt` Argumentos possíveis: (none), `4`, `5` Utiliza PyQt. Se o port é parte do próprio PyQT, defina `PYQT_DIST`. Use a variável `USE_PYQT` para selecionar os componentes que o port precisa. Os componentes disponíveis são: * `core` * `dbus` * `dbussupport` * `demo` * `designer` * `designerplugin` * `doc` * `gui` * `multimedia` * `network` * `opengl` * `qscintilla2` * `sip` * `sql` * `svg` * `test` * `webkit` * `xml` * `xmlpatterns` Estes componentes só estão disponíveis com PyQT4: * `assistant` * `declarative` * `help` * `phonon` * `script` * `scripttools` Estes componentes só estão disponíveis com PyQT5: * `multimediawidgets` * `printsupport` * `qml` * `serialport` * `webkitwidgets` * `widgets` A dependência padrão para cada componente são build e run-time, para selecionar apenas build ou run, adicione `_build` ou `_run` para o nome do componente. Por exemplo: [.programlisting] .... USES= pyqt USE_PYQT= core doc_build designer_run .... [[uses-python]] == `python` Argumentos possíveis: (none), `_XY_`, `_X.Y+_`, `_-XY_`, `_XY-ZA_`, `patch`, `build`, `run`, `test` -Utiliza Python. Uma versão suportada ou um intervalo de versões podem ser especificados. Se o Python for necessário apenas no momento de build, run-time ou para os testes, ele pode ser definido como uma dependência de build, run ou teste com `build`, `run` ou `test`. Se o Python também for necessário durante a fase de patch, use `patch`. Veja <> para maiores informações. +Utiliza Python. Uma versão suportada ou um intervalo de versões podem ser especificados. Se o Python for necessário apenas no momento de build, run-time ou para os testes, ele pode ser definido como uma dependência de build, run ou teste com `build`, `run` ou `test`. Se o Python também for necessário durante a fase de patch, use `patch`. Veja crossref:special[using-python, Usando Python] para maiores informações. `PYTHON_NO_DEPENDS=yes` pode ser usado quando as variáveis ​​exportadas pelo framework serem necessárias, mas uma dependência de Python não. Pode acontecer quando usado com <>, e o objetivo é apenas consertar os shebangs, mas não adicionar uma dependência do Python. [[uses-qmail]] == `qmail` Argumentos possíveis: (none), `build`, `run`, `both`, `vars` Utiliza package:mail/qmail[]. Com o argumento `build`, implica no `qmail` como uma dependência de build-time. `run` implica em uma dependência de run-time. Usando nenhum argumento ou o argumento `both` implica em dependências de run-time e build-time. `vars` só ira definir variáveis ​​QMAIL para o port usar. [[uses-qmake]] == `qmake` Argumentos possíveis: (none), `norecursive`, `outsource`, `no_env`, `no_configure` -Utiliza QMake para configuração. Para mais informações, veja <>. +Utiliza QMake para configuração. Para mais informações, veja crossref:special[using-qmake,Usando `qmake`]. [[uses-qt]] == `qt` Argumentos possíveis: `5`, `no_env` -Adiciona dependência de componentes Qt. `no_env` é passado diretamente para `USES= qmake`. Veja <> para maiores informações. +Adiciona dependência de componentes Qt. `no_env` é passado diretamente para `USES= qmake`. Veja crossref:special[using-qt,Usando o Qt] para maiores informações. [[uses-qt-dist]] == `qt-dist` Argumentos possíveis: (none) ou `5` e (none) ou um de `3d`, `activeqt`, `androidextras`, `base`, `canvas3d`, `charts`, `connectivity`, `datavis3d`, `declarative`, `doc`, `gamepad`, `graphicaleffects`, `imageformats`, `location`, `macextras`, `multimedia`, `networkauth`, `purchasing`, `quickcontrols2`, `quickcontrols`, `remoteobjects`, `script`, `scxml`, `sensors`, `serialbus`, `serialport`, `speech`, `svg`, `tools`, `translations`, `virtualkeyboard`, `wayland`, `webchannel`, `webengine`, `websockets`, `webview`, `winextras`, `x11extras`, `xmlpatterns` Fornece suporte para a compilação de componentes Qt 5. Ele cuida da definição do ambiente de configuração apropriado para o port compilar. [[qt5-dist-example]] .Compilando Componentes do Qt 5 [example] ==== O port é o componente `networkauth` do Qt 5, que faz parte do arquivo de distribuição `networkauth`. [.programlisting] .... PORTNAME= networkauth DISTVERSION= ${QT5_VERSION} USES= qt-dist:5 .... ==== Se `PORTNAME` não corresponder ao nome do componente, ele poderá ser passado como argumento em `qt-dist`. [[qt5-dist-example-explicit]] .Compilando Componentes do Qt 5 com Nomes Diferentes [example] ==== O port é o componente `gui` do Qt 5, que faz parte do arquivo de distribuição `base`. [.programlisting] .... PORTNAME= gui DISTVERSION= ${QT5_VERSION} USES= qt-dist:5,base .... ==== [[uses-readline]] == `readline` Argumentos possíveis: (none), `port` Usa readline como uma dependência de biblioteca e define `CPPFLAGS` e `LDFLAGS` como necessários. Se o argumento `port` é usado ou se readline não estiver presente no sistema base, adiciona uma dependência em package:devel/readline[] [[uses-samba]] == `samba` Possíveis argumentos: `build`, `env`, `lib`, `run` Manipula dependências do Samba. `env` não irá adicionar qualquer dependência e apenas irá configurar as variáveis. `build` e `run` irão adicionar dependências de run-time e build-time de [.filename]#smbd#. `lib` irá adicionar uma dependência em [.filename]#libsmbclient.so#. As variáveis ​​que são exportadas são: `SAMBAPORT`:: A origem do port padrão Samba. `SAMBAINCLUDES`:: A localização dos arquivos header do Samba. `SAMBALIBS`:: O diretório onde as bibliotecas compartilhadas do Samba estão disponíveis. [[uses-scons]] == `scons` Argumentos possíveis: (none) -Fornece suporte para o uso do package:devel/scons[]. Veja <> para maiores informações. +Fornece suporte para o uso do package:devel/scons[]. Veja crossref:special[using-scons,Usando `scons`] para maiores informações. [[uses-shared-mime-info]] == `shared-mime-info` Argumentos possíveis: (none) -Utiliza update-mime-database a partir de package:misc/shared-mime-info[]. Este uses irão adicionar automaticamente uma etapa de post-install de tal forma que o próprio port ainda possa especificar sua própria etapa de post-install, se necessário. Também adiciona uma entrada <> para o plist. +Utiliza update-mime-database a partir de package:misc/shared-mime-info[]. Este uses irão adicionar automaticamente uma etapa de post-install de tal forma que o próprio port ainda possa especificar sua própria etapa de post-install, se necessário. Também adiciona uma entrada crossref:plist[plist-keywords-shared-mime-info,`@shared-mime-info`] para o plist. [[uses-shebangfix]] == `shebangfix` Argumentos possíveis: (none) Muitos softwares usam locais incorretos para interpretadores de scripts, principalmente [.filename]#/usr/bin/perl# e [.filename]#/bin/bash#. A macro shebangfix corrige linhas shebang em scripts listados em `SHEBANG_REGEX`, `SHEBANG_GLOB` ou `SHEBANG_FILES`. `SHEBANG_REGEX`:: Contém _uma_ expressão regular estendida e é usado com o argumento `-iregex` do man:find[1]. Veja <>. `SHEBANG_GLOB`:: Contém uma lista de padrões usados com o argumento `-name` do man:find[1]. Veja <>. `SHEBANG_FILES`:: Contém uma lista de arquivos ou globs man:sh[1]. A macro shebangfix é executada a partir de `${WRKSRC}`, assim `SHEBANG_FILES` pode conter caminhos relativos a `${WRKSRC}`. Ele também pode lidar com caminhos absolutos se arquivos fora de `${WRKSRC}` requisitarem uma correção. Veja <>. Atualmente Bash, Java, Ksh, Lua, Perl, PHP, Python, Rubi, Tcl e Tk são suportados por padrão. Aqui estão três variáveis de configuração: `SHEBANG_LANG`:: A lista de interpretadores suportados. `interp_CMD`:: O caminho para o interpretador de comandos no FreeBSD. O valor padrão é `${LOCALBASE}/bin/_interp_`. `interp_OLD_CMD`:: A lista de invocações erradas de interpretadores. Estes são tipicamente caminhos obsoletos, ou caminhos usados ​​em outros sistemas operacionais que estão incorretos no FreeBSD. Eles serão substituídos pelo caminho correto na variável `interp__CMD`. + [NOTE] ==== Estes vão _sempre_ ser parte da variável `interp_OLD_CMD:"/usr/bin/envinterp" /bin/interp /usr/bin/interp /usr/local/bin/interp`. ==== + [TIP] ==== A variável `interp_OLD_CMD` contém vários valores. Qualquer entrada com espaços deve estar entre aspas. Veja <>. ==== [IMPORTANT] ==== A correção de shebangs é feita durante a fase `patch`. Se os scripts forem criados com shebangs incorretos durante a fase `build`, o processo de build (por exemplo, o script [.filename]#configure#, ou o [.filename]#Makefiles#) deve ser corrigido ou ter o caminho certo (por exemplo, com `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `MAKE_ENV` ou `MAKE_ARGS`) para gerar as shebangs certas. Os caminhos corretos para os interpretadores suportados estão disponíveis em `interp_CMD`. ==== [TIP] ==== Quando usado com <>, e o objetivo é apenas consertar os shebangs, mas a dependência de Python em si não é desejada, use a variável `PYTHON_NO_DEPENDS=yes`. ==== [[uses-shebangfix-ex-lua]] .Adicionando outro interpretadoror para `USES=shebangfix` [example] ==== Para adicionar outro interpretador, defina a variável `SHEBANG_LANG`. Por exemplo: [.programlisting] .... SHEBANG_LANG= lua .... ==== [[uses-shebangfix-ex-ksh]] .Especificando todos os Caminhos ao Adicionar um Interpretador para `USES=shebangfix` [example] ==== Se isto não estiver definido ainda, e não tiver valores padrão para `interp_OLD_CMD` e `interp_CMD` a entrada Ksh poderia ser definida como: [.programlisting] .... SHEBANG_LANG= ksh ksh_OLD_CMD= "/usr/bin/env ksh" /bin/ksh /usr/bin/ksh ksh_CMD= ${LOCALBASE}/bin/ksh .... ==== [[uses-shebangfix-ex-strange]] .Adicionando uma Localização Estranha para um Interpretador [example] ==== Alguns softwares usam localizações estranhas para um interpretador. Por exemplo, um aplicativo pode esperar que Python esteja localizado em [.filename]#/opt/bin/python2.7#. O caminho estranho a ser substituído pode ser declarado no [.filename]#Makefile# do port: [.programlisting] .... python_OLD_CMD= /opt/bin/python2.7 .... ==== [[uses-shebangfix-ex-regex]] .`USES=shebangfix` com a variável `SHEBANG_REGEX` [example] ==== Para corrigir todos os arquivos em `${WRKSRC}/scripts` finalizados com [.filename]#.pl#, [.filename]#.sh# ou [.filename]#.cgi# faça assim: [.programlisting] .... USES= shebangfix SHEBANG_REGEX= ./scripts/.*\.(sh|pl|cgi) .... [NOTE] ====== `SHEBANG_REGEX` é usada executando `find -E`, que usa expressões regulares modernas, também conhecidas como expressões regulares estendidas. Veja man:re_format[7] para maiores informações. ====== ==== [[uses-shebangfix-ex-glob]] .`USES=shebangfix` com a variável `SHEBANG_GLOB` [example] ==== Para corrigir todos os arquivos em `${WRKSRC}` finalizados com [.filename]#.pl# ou [.filename]#.sh#, faça assim: [.programlisting] .... USES= shebangfix SHEBANG_GLOB= *.sh *.pl .... ==== [[uses-shebangfix-ex-files]] .`USES=shebangfix` com a variável `SHEBANG_FILES` [example] ==== Para corrigir os arquivos [.filename]#script/foobar.pl# e [.filename]#script/*.sh# dentro de `${WRKSRC}`, faça assim: [.programlisting] .... USES= shebangfix SHEBANG_FILES= scripts/foobar.pl scripts/*.sh .... ==== [[uses-sqlite]] == `sqlite` Argumentos possíveis: (none), `2`, `3` Adiciona uma dependência SQLite. A versão padrão usada é 3, mas usar a versão 2 também é possível usando o modificador `:2`. [[uses-ssl]] == `ssl` Argumentos possíveis: (none), `build`, `run` Fornece suporte para OpenSSL. Uma dependência apenas de compilação ou run-time pode ser especificada usando `build` ou `run`. Estas variáveis estão disponíveis para uso do port, elas também são adicionadas para a variável `MAKE_ENV`: `OPENSSLBASE`:: Caminho para a base de instalação do OpenSSL. `OPENSSLDIR`:: Caminho para arquivos de configuração do OpenSSL. `OPENSSLLIB`:: Caminho para as bibliotecas do OpenSSL. `OPENSSLINC`:: Caminho para os includes do OpenSSL. `OPENSSLRPATH`:: Se definido, o caminho que o vinculador precisa usar para localizar as bibliotecas do OpenSSL. [TIP] ==== Se um port não for compilado com um flavor OpenSSL, defina a variável `BROKEN_SSL`, e possivelmente a variável `BROKEN_SSL_REASON_flavor`: [.programlisting] .... BROKEN_SSL= libressl BROKEN_SSL_REASON_libressl= needs features only available in OpenSSL .... ==== [[uses-tar]] == `tar` Argumentos possíveis: (none), `Z`, `bz2`, `bzip2`, `lzma`, `tbz`, `tbz2`, `tgz`, `txz`, `xz` Define a variável `EXTRACT_SUFX` para `.tar`, `.tar.Z`, `.tar.bz2`, `.tar.bz2`, `.tar.lzma`, `.tbz`, `.tbz2`, `.tgz`, `.txz` ou `.tar.xz` respectivamente. [[uses-tcl]] == `tcl` Argumentos possíveis: _version_, `wrapper`, `build`, `run`, `tea` Adiciona uma dependência para o Tcl. Uma versão específica pode ser requisitada usando _version_. A versão pode estar vazia, um ou mais números exatos de versão (atualmente `84`, `85` ou `86`), ou um número mínimo de versão (atualmente `84+`, `85+` ou `86+`). Para solicitar apenas um wrapper sem uma versão especifica, use `wrapper`. Uma dependência somente de compilação ou run-time pode ser especificada usando `build` ou `run`. Para compilar o port usando Tcl Extension Architecture, use o `tea`. Depois de incluir [.filename]#bsd.port.pre.mk# o port pode inspecionar os resultados usando estas variáveis: * `TCL_VER`: seleciona a versão major.minor do Tcl * `TCLSH`: caminho completo do interpretador do Tcl * `TCL_LIBDIR`: caminho das bibliotecas do Tcl * `TCL_INCLUDEDIR`: caminho dos arquivos de cabeçalho C do Tcl * `TK_VER`: versão major.minor do Tk que foi escolhida * `WISH`: caminho completo do interpretador do Tk * `TK_LIBDIR`: caminho das bibliotecas do Tk * `TK_INCLUDEDIR`: caminho dos arquivos de cabeçalho C do Tk [[uses-terminfo]] == `terminfo` Argumentos possíveis: (none) Adiciona <> ao arquivo [.filename]#plist#. Use quando o port instalar arquivos [.filename]#*.terminfo# em [.filename]#${PREFIX}/shared/misc#. [[uses-tk]] == `tk` Os mesmos argumentos para `tcl` Um pequeno wrapper ao usar os dois Tcl e Tk. As mesmas variáveis são retornadas assim como quando estiver usando Tcl. [[uses-uidfix]] == `uidfix` Argumentos possíveis: (none) Altera algum comportamento padrão (principalmente de variáveis) do sistema de compilação para permitir instalar este port como um usuário normal. Tente isso no port antes de usar <> ou de aplicar algum patch. [[uses-uniquefiles]] == `uniquefiles` Argumentos possíveis: (none), `dirs` Torna arquivos ou diretórios 'exclusivos', adicionando um prefixo ou sufixo. Se o argumento `dirs` é usado, o port precisa de um prefixo (e apenas um prefixo) baseado em `UNIQUE_PREFIX` para diretórios padrão `DOCSDIR`, `EXEMPLESDIR`, `DATADIR`, `WWWDIR`, `ETCDIR`. Estas variáveis estão disponíveis para os ports: * `UNIQUE_PREFIX`: O prefixo a ser usado para diretórios e arquivos. Padrão: `${PKGNAMEPREFIX}`. * `UNIQUE_PREFIX_FILES`: Uma lista de arquivos que precisam ser prefixados. Padrão: vazio. * `UNIQUE_SUFFIX`: O sufixo para ser usado por arquivos. Padrão: `${PKGNAMESUFFIX}`. * `UNIQUE_SUFFIX_FILES`: Uma lista de arquivos que precisam estar com um sufixo. Padrão: vazio. [[uses-varnish]] == `varnish` Argumentos possíveis: `4`, `5` Manipula dependências do Varnish Cache. `4` irá adicionar uma dependência do package:www/varnish4[]. `5` irá adicionar uma dependência do package:www/varnish5[]. [[uses-webplugin]] == `webplugin` Argumentos possíveis: (none), `ARGS` Cria e remove automaticamente links simbólicos para cada aplicação que suporta o framework do webplugin. `ARGS` pode ser um dos: * `gecko`: suporte a plug-ins baseados no Gecko * `native`: suporte a plug-ins para o Gecko, Opera e WebKit-GTK * `linux`: suporte a plug-ins do Linux * `all` (padrão, implícito): suporta todos os tipos de plug-ins * (entradas individuais): suporta apenas os navegadores listados Essas variáveis podem ser ajustadas: * `WEBPLUGIN_FILES`: Sem padrão, deve ser definido manualmente. Os arquivos de plug-in para instalar. * `WEBPLUGIN_DIR`: O diretório para instalar os arquivos de plug-in, padrão [.filename]#PREFIX/lib/browser_plugins/WEBPLUGIN_NAME#. Defina isso se o port instalar arquivos de plug-in fora do diretório padrão para previnir links simbólicos quebrados. * `WEBPLUGIN_NAME`: O diretório final para instalar os arquivos de plug-in, padrão `PKGBASE`. [[uses-xfce]] == `xfce` Argumentos possíveis: (none), `gtk2` -Fornece suporte para ports relacionados ao Xfce. Veja <> para detalhes. +Fornece suporte para ports relacionados ao Xfce. Veja crossref:special[using-xfce,Usando o Xfce] para detalhes. O argumento `gtk2` especifica que o port requer suporte a GTK2. Ele adiciona recursos adicionais fornecidos por alguns componentes principais, por exemplo, package:x11/libxfce4menu[] e package:x11-wm/xfce4-panel[]. [[uses-xorg]] == `xorg` Argumentos possíveis: (none) Fornece uma maneira fácil para depender dos componentes X.org. Os componentes devem ser listados na variável `USE_XORG`. Os componentes disponíveis são: [[using-x11-components]] .Componentes Disponíveis do X.Org [cols="1,1", frame="none", options="header"] |=== | Nome | Descrição |`dmx` |Biblioteca de extensão DMX |`fontenc` |Biblioteca fontenc |`fontutil` |Crie um índice de arquivos de fontes X em um diretório |`ice` |Biblioteca Inter Client Exchange para X11 |`libfs` |Biblioteca FS |`pciaccess` |Biblioteca Genérica de acesso ao PCI |`pixman` |Biblioteca de manipulação de pixels de baixo nível |`sm` |Biblioteca de Gerenciamento de Sessão para X11 |`x11` |Biblioteca X11 |`xau` |Biblioteca do Protocolo de Autenticação para o X11 |`xaw` |Biblioteca de Widgets do X Athena |`xaw6` |Biblioteca de Widgets do X Athena |`xaw7` |Biblioteca de Widgets do X Athena |`xbitmaps` |Arquivos bitmaps do X.Org |`xcb` |Biblioteca do protocolo X C-language Binding (XCB) |`xcomposite` |Biblioteca de extensão X Composite |`xcursor` |Biblioteca de carregamento do cursor X no lado do cliente |`xdamage` |Biblioteca de extensão X Damage |`xdmcp` |Biblioteca do Protocolo de Controle do X Display Manager |`xext` |Biblioteca de Extensão X11 |`xfixes` |Biblioteca de extensão X Fixes |`xfont` |Biblioteca de fontes do X |`xfont2` |Biblioteca de fontes do X |`xft` |API de fontes do lado do cliente para aplicativos X |`xi` |Biblioteca de extensão X Input |`xinerama` |Biblioteca X11 Xinerama |`xkbfile` |Biblioteca XKB |`xmu` |Biblioteca de Utilitários Diversos do X |`xmuu` |Biblioteca de Utilitários Diversos do X |`xorg-macros` |Macros aclocal de desenvolvimento X.Org |`xorg-server` |Servidor X do X.Org e programas relacionados |`xorgproto` |xorg protocol headers |`xpm` |Biblioteca Pixmap do X |`xpresent` |Biblioteca de Extensão X Present |`xrandr` |Biblioteca de extensão X Resize e Rotate |`xrender` |Biblioteca de extensão X Render |`xres` |Biblioteca de uso X Resource |`xscrnsaver` |Biblioteca XScrnSaver |`xshmfence` |Memória compartilhada 'SyncFence' primitiva de sincronização |`xt` |Biblioteca X Toolkit |`xtrans` |Código de rede abstrato para X |`xtst` |Extensão X Test |`xv` |Biblioteca de Extensão X Video |`xvmc` |Biblioteca X Video Extension Motion Compensation |`xxf86dga` |X DGA Extension |`xxf86vm` |Extensão X Vidmode |=== [[uses-xorg-cat]] == `xorg-cat` Argumentos possíveis: `app`, `data`, `doc`, `driver`, `font`, `lib`, `proto`, `util`, `xserver` e (none) ou um de `autotools` (default), `meson` Forneça suporte para compilação de componentes Xorg. Ele cuida da definição de dependências comuns e de um ambiente de configuração apropriado necessário. Isso é destinado apenas aos componentes do Xorg. A categoria deve corresponder às categorias upstream. O segundo argumento é o sistema de compilação a ser usado. autotools é o padrão, mas meson também é suportado. [[uses-zip]] == `zip` Argumentos possíveis: (none), `infozip` Indica que os arquivos de distribuição usam o algoritmo de compactação ZIP. Para arquivos que usam o algoritmo InfoZip, o argumento `infozip` deve ser passado para definir as dependências apropriadas. diff --git a/documentation/content/pt-br/books/porters-handbook/versions/chapter.adoc b/documentation/content/pt-br/books/porters-handbook/versions/_index.adoc similarity index 100% rename from documentation/content/pt-br/books/porters-handbook/versions/chapter.adoc rename to documentation/content/pt-br/books/porters-handbook/versions/_index.adoc