FAQ

  1. I am having troubles when building newlib. It complains it cannot find install, etc.. Why does this occur?

    You must configure and build newlib in a directory separate from the source tree. Typically, you make a build directory, cd into it and run:

    ${FULL_PATH_TO_SRC}/src/configure --prefix=`pwd` --target=XXX
    back to top

  2. I am having problems when building newlib. It is not referring to the cross-compiler that it should, based on the --target setting. What is wrong?

    When you configure you must configure from the top-level of the src directory. You do not configure from newlib's directory. The top-level configure script will eventually configure newlib for you. Since newlib is a target library it actually configures when you make all or make all-target-newlib.

    back to top

  3. I want to have newlib built with gcc and other components from the net. How do I do this?

    For cross-compilation info, check out the crossgcc faq. When setting up a unified source directory, remember that the newlib subdirectory should be a sibling to gcc, binutils, etc.. All of these net projects share a top-level directory so you only want to copy or link the tools/libraries subdirectories specifically. For example, the newlib project when downloaded has a src directory with a number of subdirectories including newlib and libgloss. When gcc is downloaded, it too has a src directory with a gcc subdirectory. To bring in newlib and libgloss, a user could link the newlib and libgloss subdirectories of the newlib source tree into the src tree of gcc.

    back to top

  4. What configuration options are available for newlib?

    To see a list of configuration options specific for newlib, run:

    ${FULL_PATH_TO_SRC}/src/newlib/configure --help Of interest are the --enable-target-optspace, --enable-newlib-mb, and --enable-newlib-hw-fp options.

    The optspace option allows certain functions to use algorithms designed for space rather than speed. It also compiles the whole library with -Os.

    The newlib-mb option allows multibyte support. This multibyte support enables three special locales: "C-JIS", "C-SJIS", and "C-EUCJP". These locales are basically the "C" locale with multibyte-function support for the specified Japanese character sets. The multibyte support extends to the mb and wc functions in stdlib as well as format characters for the printf and scanf family of routines.

    The newlib-hw-fp option causes the library to use a set of math routines that use floating-point algorithms. By default, the newlib library math routines use integer-based algorithms to perform the desired functionality. For a platform that has fast floating-point support, the floating-point algorithms may be faster and smaller.

    back to top

  5. What does newlib do for chips that have optional features such as endianness or has different models with distinct instruction sets?

    Newlib, by default, builds "multilibs". What this term means is that multiple versions of newlib are built according to a set of permutated options determined by the compiler. For example, for a chip that can be set to either run in big-endian or little-endian mode, the compiler would designate target libraries be built with each endianness. In the case where there are multiple features, the compiler will designate libraries be built with permutations of the various options so as to cover all possible combinations.

    When built, the compiler sets up a list of option permutations and a set of directory names to place multilibs in. This information is exposed externally via the "print-multi-lib" option which outputs the list in a compact form. When the compiler is called to compile and link an application, it recognizes multilib-designated options and knows which versions of target libraries, such as newlib, to link with which has been built with the same options. For this to work, you want gcc and newlib installed in the same directory. You also want to link using the compiler rather than linking objects via "ld". The ld linker does not accept compiler options and thus does not know how to map to the correct target libraries. If you decide to use ld instead of gcc to link, you will be forced to specify the location of newlib manually.

    When newlib is building, it simply invokes the compiler with the -print-multi-lib option to get the set of multilibs it should create. Try xxx-yyy-gcc -print-multi-lib to see the list of permutations that will be used for your platform to build newlib.

    For more information about how to interpret the output of -print-multi-lib, see the gcc documentation. For problems relating to which multilibs are selected and which are missing, contact the gcc list.

    back to top

  6. What steps do I need to do to port newlib to a new platform?

    A basic port needs to alter a number of files and add some directories.

    1. Add a subdirectory to the newlib/libc/machine directory for your platform

      In this directory you need to have a setjmp/longjmp implementation. This is required because setjmp/longjmp usually is assembler. Look at the libc/machine/fr30 directory and copy/modify the files in there.

    2. Edit newlib/libc/include/machine/ieeefp.h

      This defines the ieee endianness for your platform. The compiler should be defining something that identifies your machine. In some cases, the endianness may be a compiler-option so you may have to check another define in addition to your platform identifier. See examples in the file.

    3. Edit newlib/libc/include/machine/setjmp.h

      You need to specify the setjmp buffer characteristics to match up with your setjmp/longjmp implementation. This is just the size of the setjmp buffer. See file for examples.

    4. Edit newlib/libc/include/sys/config.h

      This has various defines as needed. Mostly, it defines some max values. There are defaults that may apply to your platform in which case you needn't do anything.

    5. Edit configure.host

      You need to add your configuration so newlib can recognize it. You should specify your new machine directory for your platform via the machine_dir variable. If needed, you can add special newlib compile flags. The sys_dir is for OS stuff so you won't need to alter that. Older platforms used the sys_dir to implement syscalls but this is not correct and is a historical nuisance. The syscall_dir is a choice, but I recommend as a default to specify syscall_dir=syscalls. Read the comments in newlib/libc/include/reent.h for an explanation of choices.

    6. Add a platform subdirectory to libgloss

      You need to add a bsp for your platform. This is the minimum set of syscalls needed by newlib and any linker scripts needed. This varies from board to board (it can also be a simulator). See the mn10300 or fr30 for examples. You will need to edit configure.in and regenerate configure so it will build your new files. By default you get libnosys which gives you a set of default syscall stubs. The majority of the stubs just return failure. You still need to supply an __exit routine. This can be as simple as generating an exception to stop the program.

    7. Possibly override header files

      If you need to override any default machine header files, you can add a machine directory to newlib/libc/machine/ Header files in that subdirectory will overwrite the defaults found in newlib/libc/include/machine. You will likely not need to do this.

    This assumes you have already handled adding your new configuration to the top directory files.

    Now linux is a different animal. It is an OS that has an extensive set of syscalls. If you look in the newlib/libc/sys/linux directory, you will find a number of syscalls there (e.g. see io.c). There is a set of basic syscall macros that are defined for the particular platform. For the x86, you will find these macros defined in newlib/libc/sys/linux/machine/i386/syscall.h file. At the moment, linux support is only for x86. To add another platform, the syscall.h file would have to be supplied for the new platform plus some other platform-specific files would need to be ported as well.

    back to top

  7. How do I regenerate various configuration files?

    There are a few things to understand. First of all, aclocal needs to be run first where ever there is a configure.ac or configure.in file. The aclocal tool creates a set of macros that will be used by the generated configure script. This enables the end-user not to have to install autoconf or automake on their systems to run the configuration. The aclocal tool uses the configure.in or configure.ac files to determine what is needed so you need to run this whenever you change these files. The output of running aclocal is the aclocal.m4 file.

    Now, there is a special macro for newlib called NEWLIB_CONFIGURE. It is defined in the top-level newlib directory in acinclude.m4 and it has common logic such that special newlib configuration variables are handled. This macro should be included in every configure.in or configure.ac file in the newlib tree. Every call to aclocal should use a -I parameter that points to the newlib top-level directory. In addition, there are special m4 files in the top-level src directory that is the parent of newlib. This directory should also be specified via a -I parameter.

    The next thing to run is autoconf in a directory where there is a configure.in or configure.ac file. This generates the configure script for that directory. In general, you don't need to specify any parameters when calling autoconf.

    Finally, there is automake. Automake should be run after autoconf and specify a Makefile parameter for every directory that has a Makefile.am file. The role of automake is to take the Makefile.am file plus the configure script and create a Makefile.in which is the template for the configure script to create the final Makefile during configuration. In newlib, we run automake from the directory that contains a configure script and specify all sub-directories that do not have their own configure script. In addition, a special option is used: --cygnus. This determines special targets that will ultimately end up in the final Makefile. For example, the newlib/libc directory has a number of sub-directories that do not have their own configuration (e.g. string, stdlib, ctype). To generate Makefile.in files for each, we specify: automake --cygnus Makefile string/Makefile stdlib/Makefile ctype/Makefile ...).

    So, when do each of the tools need to be run? If you modify configure.in or configure.ac or the top-level acinclude.m4 file, you must run aclocal, then autoconf, and finally automake for that directory and all sub-directories that do not have their own configure.in/configure.ac. If all you change is Makefile.am, then all you need to run is automake. If you change no configuration input files, then you need not regenerate anything.

    The following shows the steps needed to be run in newlib/libc if one changes the configure.in file found in that directory.

    aclocal -I .. -I../.. autoconf automake --cygnus Makefile argz/Makefile ctype/Makefile errno/Makefile \ iconv/Makefile locale/Makefile misc/Makefile posix/Makefile reent/Makefile \ search/Makefile signal/Makefile stdio/Makefile stdio64/Makefile \ stdlib/Makefile string/Makefile syscalls/Makefile time/Makefile \ unix/Makefile iconv/ccs/Makefile iconv/ces/Makefile iconv/lib/Makefile \ iconv/ccs/binary/Makefile

    Note how we do not specify the machine or sys sub-directories. This is because they both have their own configure.in files. Also note that we must specify a number of subdirectories of iconv. This is because they have Makefile.am files and the closest configure.in/configure.ac parent file for them is the one found in libc.

    back to top

  8. What version of autotools should I use for regenerating files?

    Newlib doesn't attempt to be bleeding-edge when it comes to autotool usage. Each snapshot release will be made using a set of autotools felt to be stable. You can determine the versions that were used by looking at the generated files (each documents what level was used). For example, to see the level of autoconf, look inside the configure script you wish to regenerate. To see the level of automake, look inside a Makefile.in file. Using the same version of the tool as was used previously is usually recommended, but you may have more recent tools installed on your system. If you do not have commit rights, you should omit submitting generated files and allow a committer to regenerate them for you. In some cases, committers may start using newer versions of autotools for various changes as we approach the date of a snapshot.

    back to top

  9. When and how is newlib released?

    Newlib currently has a yearly snapshot which is taken in December. The snapshot is taken from the source code repository and tar'd. The tar file is made available here through the newlib web-site: http://sourceware.org/newlib. Newlib does not have a formal test cycle so a snapshot is not necessarily more stable than the current repository contents. Testing does occur as a number of consumers of newlib such as Cygwin and RTEMS do extra testing as time draws nearer to a snapshot. In general, one is advised to try using the source repository as it contains the latest fixes. No fixes are posted to snapshot releases.

    back to top

  10. What is the libm/mathfp directory?

    The libm/mathfp directory was a failed experiment to implement the libm library using floating-point algorithms. The idea was to make this optional for platforms that had floating-point instructions. Some of the algorithms use recursion and are simply inaccurate, especially when presented the full range of possible input arguments such as very large and very small values. The library used to be enabled via the --enable-newlib-hw-fp option, but has been disabled in configure.in as of Oct 24/2012.

    back to top