/*
* Instructions for building BLCR with a cross-compiler.
*
* NOTE: Cross-compilation of BLCR is experimental at this point and may
* not always go smoothly. We are currently considering only systems for
* which the cross-compilation tool-chain has been installed in what we
* believe is a "standard" manner (tool-chain executables prefixed with
* a host-tuple recognized by config.sub).
*
* We welcome your feedback on how these instructions and/or the script
* output by this program can be made more general and more robust.
*
* In the instructions that follow, we use "Target" to refer to the platform
* on which you plan to run BLCR and "Build" to refer to the platform on
* which you plan to compile BLCR.
*
* We recommend you read all the steps before you begin following any of them.
*
* 1. "Build the cross-helper program"
* This file is a C source file. On Build, compile it with the cross-
* compiler, using the options you need/want to pass at configure time (to
* get the same ABI, libc version, etc.). Examples of options to pass
* include "-m64" if using a biarch compiler that defaults to 32-bit.
* Unless you dissable (see below) CHECK_LINUXTHREADS, you will need to
* pass -lpthread to link correctly.
* If your compilation fails with errors, you may need to disable building
* one or more of the tests. To do so, try changing the CHECK_* settings
* below to disable the problematic test(s). However, if you do so you'll
* need some other way to determine the test result. So, you'll probably
* want to contact us at checkpoint@lbl.gov for assistance.
*
* 2. "Run the cross-helper program"
* Run the built program on Target, saving the output to a file in the top-
* level BLCR source directory on Build. Getting the executable from
* Build to Target and the output file back to Build are up to you - we
* have no way to portably automate this.
* In what follows, we'll assume you've named the file "cross-configure",
* but any name is fine. However, it is crucial that the file be saved
* in the top-level source directory (the same directory that contains
* "configure").
*
* 3. "Edit the cross-configure script"
* Edit the new cross-configure script for completeness, fixing anything
* you can identify as incorrect and adding manually-determined answers
* for any CHECK_* settings you disabled in step #1.
* Look for the string "%MISSING%" to identify anything that is required
* before you can move to the next step.
* The one thing you will always need to supply is the Target type.
* If using a standard installation of a gcc cross compiler, then the
* type string is the prefix of the cross-compiler, minus the final
* hyphen. For instance, if in step #1 you build this file using
* i586-redhat-linux-gcc, then TARGET_TYPE should be "i586-redhat-linux".
*
* 4. "Make the cross-configure script executable"
* chmod +x cross-configure
*
* 5. "Satisfy the build prerequisites"
* Ensure that you have, on the Build system, configured kernel source
* for the Target system as described in doc/html/BLCR_Admin_Guide.html
* and in the FAQ entry "What if I my kernel sources are unconfigured?"
* in doc/html/FAQ/html. You will also need, on the Build system, either
* the "System.map" file or the "vmlinux" file from the Target's kernel.
* If you need to use the instructions in the FAQ to configure your kernel
* sources, then you'll need to replace "make" in those instructions with
* "make ARCH=<host_arch> CROSS_COMPILE=<tool_prefix>".
*
* 6. "Prepare configure options"
* Read the BLCR Admin Guide (in doc/html) to understand what options you
* want or need to pass to "configure", but don't run configure directly!
* In the next step we'll run the newly create "cross-configure" script
* instead. In this step just determine the options you'll need.
* + You must provide the option --with-linux=[DIR] and one of either
* --with-system-map=[FILE] or --with-vmlinux=[FILE]. Otherwise the
* configure logic will default to trying to use the currently running
* kernel on the Build machine!
* + When considering a value for --prefix (or any other options that will
* determine placement of BLCR files), specify the values as they will
* appear in the Target's filesystem regardless of if/how they may appear
* on the Build machine.
* + If you want to build a BLCR test suite runnable on Target, include
* --enable-testsuite in your options (see the step "Running the tests on
* Target", below, for more details on this). We recommend this option.
* + If in step 1 you passed any compiler flags to control ABI, then we
* recommend that you add them to the definition of CC. For instance,
* for a biarch compiler defaulting to 32-bits, you might pass
* CC='ppc-linux-gcc -m64' on the cross-configure command line.
*
* 7. "Run the cross-configure script"
* On Build, run "cross-configure" with the options you determined in
* the previous step.
*
* 8. "Compile BLCR"
* On Build, run "make" to build BLCR using the cross tool-chain.
* Don't run "make install" yet; it is covered in the steps that follow.
* Don't try to run "make insmod" or "make check" on Build, since they
* use binaries that have been built for Target. However, you may
* optionally run "make tests" on the Build machine to compile (but not
* run) the test programs, though if you configured with --enable-testsuite
* then they will be compiled by default.
*
* 9. "Installing BLCR (part 1 of 3)"
* When considering --prefix and related configure options above, we told
* you to consider only the paths as they appear in the filesystem of the
* Target system. This is important because some of these paths get encoded
* in the programs and/or libraries. However, the next step is to run
* the installation step on Build. So, now we will assume that you have
* one of two situations. If your situation falls somewhere in between,
* then we recommend using case B.
* A) The Target filesystem is mounted (writable) on the Build machine,
* rooted at some single prefix such as /export/example.
* B) The Target filesystem is not mounted on the Build machine.
* On Build, run "make install DESTDIR=<PATH>" where the value of <PATH>
* is your mount point for case A, or any empty directory of your choosing
* for case B (something like /tmp/blcr-destdir is a good choice).
*
* 10. "Installing BLCR (part 2 of 3)"
* If your system fell into case A of the previous step, then your files
* are now present on the Target filesystem. If your system fell into case
* B, then you now must use some mechanism of your choice to copy all the
* files in the chosen DESTDIR to the Target filesystem. You can then
* remove the temporary directory you used for DESTDIR.
*
* 11. "Installing BLCR (part 3 of 3)"
* You should now connect to Target, and continue the steps in the BLCR
* Admin Guide for "Loading the Kernel Modules", "Updating ld.so.cache"
* and "Configuring Users' Environments".
*
* 12. [OPTIONAL] "Running the tests on Target"
* Note that while releases prior to 0.8.0 required "perl" on Target to
* run most of the tests, that is no longer the case.
* There are two possible ways to run the BLCR test suite on Target:
* A) "Option 1 - cross compilation"
* If you passed "--enable-testsuite" to the cross-configure script,
* then you will find a script named "RUN_ME" installed in
* "$prefix/libexec/blcr-testsuite" on Target. Once you have loaded the
* kernel modules and setup your environment correctly (LD_LIBRARY_PATH
* in particular), on Target, you can execute "RUN_ME" to run the same
* testsuite that "make check" runs in a native build.
* A message like
* ERROR: ld.so: object 'libcr.so.0' from LD_PRELOAD cannot be preloaded: ignored.
* is a sign that you have not set LD_LIBRARY_PATH correctly, or if you
* installed in a "system directory" it may mean you need to run
* "ldconfig" as root to update /etc/ld.so.cache.
* If you are concerned over disk space, you may safely remove the
* blcr-testsuite directory when you are done with it - no other parts
* of BLCR depend on it existing.
* B) "Option 2 - native compilation"
* If you have a native tool-chain for compilation on Target you also
* have the option to configure BLCR on Target to build only the
* testsuite. To do so, run
* "configure --with-installed-util --with-installed-modules \
* --with-installed-libcr"
* on Target, adding any --prefix or related options passed to the
* cross-configure script on Build. However, you don't need to pass
* the --with-linux, --with-system-map or --with-vmlinux options.
* When invoked this way, configure will do only a minimum amount of
* work, far less than when configuring for a full build with the
* kernel modules. You can then run "make -C tests check" to build
* and run the testsuite (without the lengthy build of the library
* and kernel modules).
*
* 13. [OPTIONAL] "BLCR Manual pages"
* Because of the way BLCR generates its man pages, cross-compiled builds
* don't have man pages. If you need/want man pages on the Target system,
* then you can build BLCR natively on any system of your choosing and
* manually copy the resulting man pages to Target. There are no platform-
* specific elements to the man pages.
*
*
* $Id: cross_helper.c,v 1.10 2008/08/27 18:47:55 phargrov Exp $
*/
/* BEGIN CHECK_* variables for optional configuration. */
#define CHECK_STACK_DIRECTION 1
#define CHECK_SIGNUM 1
#define CHECK_LINUXTHREADS 1
/* END optional configuration.
* If you think you need to modify anything below this line,
* then please contact us at checkpoint@lbl.gov.
*
*/
#include <stdio.h>
#include <stdlib.h>
#ifndef CHECK_STACK_DIRECTION
#define CHECK_STACK_DIRECTION 1
#endif
#ifndef CHECK_SIGNUM
#define CHECK_SIGNUM 1
#endif
#ifndef CHECK_LINUXTHREADS
#define CHECK_LINUXTHREADS 1
#endif
static void die(const char *msg) {
fprintf(stderr, msg);
exit(1);
}
#if CHECK_STACK_DIRECTION
static void cross_stack_direction(void) {
static char *addr = 0;
auto char dummy;
if (addr == 0) {
addr = &dummy;
cross_stack_direction();
return;
}
printf("cross_stack_direction=%d\n", (&dummy > addr) ? 1 : -1);
}
#else
static void cross_stack_direction(void) {
printf("cross_stack_direction=%%MISSING%%\n");
}
#endif
#if CHECK_SIGNUM
extern int __libc_allocate_rtsig(int);
static void cross_signum(void) {
int i = __libc_allocate_rtsig(0);
if (i <= 0) die("Unable to determine CR_SIGNUM\n");
printf("cross_signum=%d\n", i);
}
#else
static void cross_signum(void) {
printf("cross_signum=%%MISSING%%\n");
}
#endif
#if CHECK_LINUXTHREADS
#include <sys/types.h>
#include <unistd.h>
#include <pthread.h>
static void *thread_pid(void *arg) { return (void *)(long)getpid(); }
static void cross_linuxthreads(void) {
pthread_t th;
void *join_val;
if (0 != pthread_create(&th, NULL, &thread_pid, NULL)) {
die("Error calling pthread_create()\n");
}
if (0 != pthread_join(th, &join_val)) {
die("Error calling pthread_join()\n");
}
printf("cross_linuxthreads=%i\n", (long)join_val != (long)getpid());
}
#else
static void cross_linuxthreads(void) {
printf("cross_linuxthreads=%%MISSING%%\n");
}
#endif
static void print_header(void) {
puts(
"# Automatically-generated file for cross-configuration of BLCR.\n"
"# You will always need to perform at least some manual editing.\n"
"# So, see the file \"cross_helper.c\" for instructions.\n"
"\n"
"# You always need to set this one manually.\n"
"TARGET_TYPE=%MISSING%\n"
"\n"
);
}
static void print_trailer(void) {
puts(
"extra_conf_args=\"cross_signum=$cross_signum cross_stack_direction=$cross_stack_direction cross_linuxthreads=$cross_linuxthreads cross_linuxthreads_static=$cross_linuxthreads_static\"\n"
"\n"
"srcdir=`dirname $0`\n"
"if test ! -f \"$srcdir/configure\" ; then\n"
" echo \"The script $0 must be in the same directory as the configure script.\"\n"
" exit 1\n"
"fi\n"
"${srcdir}/configure --host=$TARGET_TYPE --program-prefix='' $extra_conf_args \"$@\"\n"
);
}
int main(void) {
print_header();
cross_stack_direction();
cross_signum();
cross_linuxthreads();
puts( "\n"
"# ONLY if configuring with --enable-static or --disable-shared, you'll need to\n"
"# set cross_linuxthreads_static on the following line. The value to use can be\n"
"# taken from the cross_linuxthreads value output by a version of the \"cross_helper\"\n"
"# compiled with -static.\n"
"# If NOT passing --enable-static or --disable-shared at configure time, this\n"
"# value will be unused and need not be set.\n"
"cross_linuxthreads_static=%MISSING%\n"
"\n"
);
print_trailer();
return 0;
}
* Instructions for building BLCR with a cross-compiler.
*
* NOTE: Cross-compilation of BLCR is experimental at this point and may
* not always go smoothly. We are currently considering only systems for
* which the cross-compilation tool-chain has been installed in what we
* believe is a "standard" manner (tool-chain executables prefixed with
* a host-tuple recognized by config.sub).
*
* We welcome your feedback on how these instructions and/or the script
* output by this program can be made more general and more robust.
*
* In the instructions that follow, we use "Target" to refer to the platform
* on which you plan to run BLCR and "Build" to refer to the platform on
* which you plan to compile BLCR.
*
* We recommend you read all the steps before you begin following any of them.
*
* 1. "Build the cross-helper program"
* This file is a C source file. On Build, compile it with the cross-
* compiler, using the options you need/want to pass at configure time (to
* get the same ABI, libc version, etc.). Examples of options to pass
* include "-m64" if using a biarch compiler that defaults to 32-bit.
* Unless you dissable (see below) CHECK_LINUXTHREADS, you will need to
* pass -lpthread to link correctly.
* If your compilation fails with errors, you may need to disable building
* one or more of the tests. To do so, try changing the CHECK_* settings
* below to disable the problematic test(s). However, if you do so you'll
* need some other way to determine the test result. So, you'll probably
* want to contact us at checkpoint@lbl.gov for assistance.
*
* 2. "Run the cross-helper program"
* Run the built program on Target, saving the output to a file in the top-
* level BLCR source directory on Build. Getting the executable from
* Build to Target and the output file back to Build are up to you - we
* have no way to portably automate this.
* In what follows, we'll assume you've named the file "cross-configure",
* but any name is fine. However, it is crucial that the file be saved
* in the top-level source directory (the same directory that contains
* "configure").
*
* 3. "Edit the cross-configure script"
* Edit the new cross-configure script for completeness, fixing anything
* you can identify as incorrect and adding manually-determined answers
* for any CHECK_* settings you disabled in step #1.
* Look for the string "%MISSING%" to identify anything that is required
* before you can move to the next step.
* The one thing you will always need to supply is the Target type.
* If using a standard installation of a gcc cross compiler, then the
* type string is the prefix of the cross-compiler, minus the final
* hyphen. For instance, if in step #1 you build this file using
* i586-redhat-linux-gcc, then TARGET_TYPE should be "i586-redhat-linux".
*
* 4. "Make the cross-configure script executable"
* chmod +x cross-configure
*
* 5. "Satisfy the build prerequisites"
* Ensure that you have, on the Build system, configured kernel source
* for the Target system as described in doc/html/BLCR_Admin_Guide.html
* and in the FAQ entry "What if I my kernel sources are unconfigured?"
* in doc/html/FAQ/html. You will also need, on the Build system, either
* the "System.map" file or the "vmlinux" file from the Target's kernel.
* If you need to use the instructions in the FAQ to configure your kernel
* sources, then you'll need to replace "make" in those instructions with
* "make ARCH=<host_arch> CROSS_COMPILE=<tool_prefix>".
*
* 6. "Prepare configure options"
* Read the BLCR Admin Guide (in doc/html) to understand what options you
* want or need to pass to "configure", but don't run configure directly!
* In the next step we'll run the newly create "cross-configure" script
* instead. In this step just determine the options you'll need.
* + You must provide the option --with-linux=[DIR] and one of either
* --with-system-map=[FILE] or --with-vmlinux=[FILE]. Otherwise the
* configure logic will default to trying to use the currently running
* kernel on the Build machine!
* + When considering a value for --prefix (or any other options that will
* determine placement of BLCR files), specify the values as they will
* appear in the Target's filesystem regardless of if/how they may appear
* on the Build machine.
* + If you want to build a BLCR test suite runnable on Target, include
* --enable-testsuite in your options (see the step "Running the tests on
* Target", below, for more details on this). We recommend this option.
* + If in step 1 you passed any compiler flags to control ABI, then we
* recommend that you add them to the definition of CC. For instance,
* for a biarch compiler defaulting to 32-bits, you might pass
* CC='ppc-linux-gcc -m64' on the cross-configure command line.
*
* 7. "Run the cross-configure script"
* On Build, run "cross-configure" with the options you determined in
* the previous step.
*
* 8. "Compile BLCR"
* On Build, run "make" to build BLCR using the cross tool-chain.
* Don't run "make install" yet; it is covered in the steps that follow.
* Don't try to run "make insmod" or "make check" on Build, since they
* use binaries that have been built for Target. However, you may
* optionally run "make tests" on the Build machine to compile (but not
* run) the test programs, though if you configured with --enable-testsuite
* then they will be compiled by default.
*
* 9. "Installing BLCR (part 1 of 3)"
* When considering --prefix and related configure options above, we told
* you to consider only the paths as they appear in the filesystem of the
* Target system. This is important because some of these paths get encoded
* in the programs and/or libraries. However, the next step is to run
* the installation step on Build. So, now we will assume that you have
* one of two situations. If your situation falls somewhere in between,
* then we recommend using case B.
* A) The Target filesystem is mounted (writable) on the Build machine,
* rooted at some single prefix such as /export/example.
* B) The Target filesystem is not mounted on the Build machine.
* On Build, run "make install DESTDIR=<PATH>" where the value of <PATH>
* is your mount point for case A, or any empty directory of your choosing
* for case B (something like /tmp/blcr-destdir is a good choice).
*
* 10. "Installing BLCR (part 2 of 3)"
* If your system fell into case A of the previous step, then your files
* are now present on the Target filesystem. If your system fell into case
* B, then you now must use some mechanism of your choice to copy all the
* files in the chosen DESTDIR to the Target filesystem. You can then
* remove the temporary directory you used for DESTDIR.
*
* 11. "Installing BLCR (part 3 of 3)"
* You should now connect to Target, and continue the steps in the BLCR
* Admin Guide for "Loading the Kernel Modules", "Updating ld.so.cache"
* and "Configuring Users' Environments".
*
* 12. [OPTIONAL] "Running the tests on Target"
* Note that while releases prior to 0.8.0 required "perl" on Target to
* run most of the tests, that is no longer the case.
* There are two possible ways to run the BLCR test suite on Target:
* A) "Option 1 - cross compilation"
* If you passed "--enable-testsuite" to the cross-configure script,
* then you will find a script named "RUN_ME" installed in
* "$prefix/libexec/blcr-testsuite" on Target. Once you have loaded the
* kernel modules and setup your environment correctly (LD_LIBRARY_PATH
* in particular), on Target, you can execute "RUN_ME" to run the same
* testsuite that "make check" runs in a native build.
* A message like
* ERROR: ld.so: object 'libcr.so.0' from LD_PRELOAD cannot be preloaded: ignored.
* is a sign that you have not set LD_LIBRARY_PATH correctly, or if you
* installed in a "system directory" it may mean you need to run
* "ldconfig" as root to update /etc/ld.so.cache.
* If you are concerned over disk space, you may safely remove the
* blcr-testsuite directory when you are done with it - no other parts
* of BLCR depend on it existing.
* B) "Option 2 - native compilation"
* If you have a native tool-chain for compilation on Target you also
* have the option to configure BLCR on Target to build only the
* testsuite. To do so, run
* "configure --with-installed-util --with-installed-modules \
* --with-installed-libcr"
* on Target, adding any --prefix or related options passed to the
* cross-configure script on Build. However, you don't need to pass
* the --with-linux, --with-system-map or --with-vmlinux options.
* When invoked this way, configure will do only a minimum amount of
* work, far less than when configuring for a full build with the
* kernel modules. You can then run "make -C tests check" to build
* and run the testsuite (without the lengthy build of the library
* and kernel modules).
*
* 13. [OPTIONAL] "BLCR Manual pages"
* Because of the way BLCR generates its man pages, cross-compiled builds
* don't have man pages. If you need/want man pages on the Target system,
* then you can build BLCR natively on any system of your choosing and
* manually copy the resulting man pages to Target. There are no platform-
* specific elements to the man pages.
*
*
* $Id: cross_helper.c,v 1.10 2008/08/27 18:47:55 phargrov Exp $
*/
/* BEGIN CHECK_* variables for optional configuration. */
#define CHECK_STACK_DIRECTION 1
#define CHECK_SIGNUM 1
#define CHECK_LINUXTHREADS 1
/* END optional configuration.
* If you think you need to modify anything below this line,
* then please contact us at checkpoint@lbl.gov.
*
*/
#include <stdio.h>
#include <stdlib.h>
#ifndef CHECK_STACK_DIRECTION
#define CHECK_STACK_DIRECTION 1
#endif
#ifndef CHECK_SIGNUM
#define CHECK_SIGNUM 1
#endif
#ifndef CHECK_LINUXTHREADS
#define CHECK_LINUXTHREADS 1
#endif
static void die(const char *msg) {
fprintf(stderr, msg);
exit(1);
}
#if CHECK_STACK_DIRECTION
static void cross_stack_direction(void) {
static char *addr = 0;
auto char dummy;
if (addr == 0) {
addr = &dummy;
cross_stack_direction();
return;
}
printf("cross_stack_direction=%d\n", (&dummy > addr) ? 1 : -1);
}
#else
static void cross_stack_direction(void) {
printf("cross_stack_direction=%%MISSING%%\n");
}
#endif
#if CHECK_SIGNUM
extern int __libc_allocate_rtsig(int);
static void cross_signum(void) {
int i = __libc_allocate_rtsig(0);
if (i <= 0) die("Unable to determine CR_SIGNUM\n");
printf("cross_signum=%d\n", i);
}
#else
static void cross_signum(void) {
printf("cross_signum=%%MISSING%%\n");
}
#endif
#if CHECK_LINUXTHREADS
#include <sys/types.h>
#include <unistd.h>
#include <pthread.h>
static void *thread_pid(void *arg) { return (void *)(long)getpid(); }
static void cross_linuxthreads(void) {
pthread_t th;
void *join_val;
if (0 != pthread_create(&th, NULL, &thread_pid, NULL)) {
die("Error calling pthread_create()\n");
}
if (0 != pthread_join(th, &join_val)) {
die("Error calling pthread_join()\n");
}
printf("cross_linuxthreads=%i\n", (long)join_val != (long)getpid());
}
#else
static void cross_linuxthreads(void) {
printf("cross_linuxthreads=%%MISSING%%\n");
}
#endif
static void print_header(void) {
puts(
"# Automatically-generated file for cross-configuration of BLCR.\n"
"# You will always need to perform at least some manual editing.\n"
"# So, see the file \"cross_helper.c\" for instructions.\n"
"\n"
"# You always need to set this one manually.\n"
"TARGET_TYPE=%MISSING%\n"
"\n"
);
}
static void print_trailer(void) {
puts(
"extra_conf_args=\"cross_signum=$cross_signum cross_stack_direction=$cross_stack_direction cross_linuxthreads=$cross_linuxthreads cross_linuxthreads_static=$cross_linuxthreads_static\"\n"
"\n"
"srcdir=`dirname $0`\n"
"if test ! -f \"$srcdir/configure\" ; then\n"
" echo \"The script $0 must be in the same directory as the configure script.\"\n"
" exit 1\n"
"fi\n"
"${srcdir}/configure --host=$TARGET_TYPE --program-prefix='' $extra_conf_args \"$@\"\n"
);
}
int main(void) {
print_header();
cross_stack_direction();
cross_signum();
cross_linuxthreads();
puts( "\n"
"# ONLY if configuring with --enable-static or --disable-shared, you'll need to\n"
"# set cross_linuxthreads_static on the following line. The value to use can be\n"
"# taken from the cross_linuxthreads value output by a version of the \"cross_helper\"\n"
"# compiled with -static.\n"
"# If NOT passing --enable-static or --disable-shared at configure time, this\n"
"# value will be unused and need not be set.\n"
"cross_linuxthreads_static=%MISSING%\n"
"\n"
);
print_trailer();
return 0;
}